Install jsdoc and add doclet stubs for all methods

Descriptions are taken from existing comments if available. The address module already has some new sample descriptions.

1 files changed, 97 insertions, 0 deletions

diff --git a/lib/address.js b/lib/address.js
index e72a2aa8..cf37d2e8 100644
--- a/lib/address.js
+++ b/lib/address.js
@@ -1,7 +1,18 @@
+/**
+ *
+ * @namespace faker.address
+ */
 function Address (faker) {
   var f = faker.fake,
       Helpers = faker.helpers;
 
+  /**
+   * Generates random zipcode from format. If format is not specified, the
+   * locale's zip format is used.
+   *
+   * @method faker.address.zipCode
+   * @param {String} format
+   */
   this.zipCode = function(format) {
     // if zip format is not specified, use the zip format defined for the locale
     if (typeof format === 'undefined') {
@@ -15,6 +26,21 @@ function Address (faker) {
     return Helpers.replaceSymbols(format);
   }
 
+  /**
+   * Generates a random localized city name. The format string can contain any
+   * method provided by faker wrapped in `{{}}`, e.g. `{{name.firstName}}` in
+   * order to build the city name.
+   *
+   * If no format string is provided one of the following is randomly used:
+   * 
+   * * `{{address.cityPrefix}} {{name.firstName}}{{address.citySuffix}}`
+   * * `{{address.cityPrefix}} {{name.firstName}}`
+   * * `{{name.firstName}}{{address.citySuffix}}`
+   * * `{{name.lastName}}{{address.citySuffix}}`
+   *
+   * @method faker.address.city
+   * @param {String} format
+   */
   this.city = function (format) {
     var formats = [
       '{{address.cityPrefix}} {{name.firstName}}{{address.citySuffix}}',
@@ -31,14 +57,28 @@ function Address (faker) {
 
   }
 
+  /**
+   * Return a random localized city prefix
+   * @method faker.address.cityPrefix
+   */
   this.cityPrefix = function () {
     return faker.random.arrayElement(faker.definitions.address.city_prefix);
   }
 
+  /**
+   * Return a random localized city suffix
+   *
+   * @method faker.address.citySuffix
+   */
   this.citySuffix = function () {
     return faker.random.arrayElement(faker.definitions.address.city_suffix);
   }
 
+  /**
+   * Returns a random localized street name
+   *
+   * @method faker.address.streetName
+   */
   this.streetName = function () {
       var result;
       var suffix = faker.address.streetSuffix();
@@ -60,6 +100,12 @@ function Address (faker) {
   //
   // TODO: change all these methods that accept a boolean to instead accept an options hash.
   //
+  /**
+   * Returns a random localized street address
+   *
+   * @method faker.address.streetAddress
+   * @param {Boolean} useFullAddress
+   */
   this.streetAddress = function (useFullAddress) {
       if (useFullAddress === undefined) { useFullAddress = false; }
       var address = "";
@@ -77,14 +123,29 @@ function Address (faker) {
       return useFullAddress ? (address + " " + faker.address.secondaryAddress()) : address;
   }
 
+  /**
+   * streetSuffix
+   *
+   * @method faker.address.streetSuffix
+   */
   this.streetSuffix = function () {
       return faker.random.arrayElement(faker.definitions.address.street_suffix);
   }
   
+  /**
+   * streetPrefix
+   *
+   * @method faker.address.streetPrefix
+   */
   this.streetPrefix = function () {
       return faker.random.arrayElement(faker.definitions.address.street_prefix);
   }
 
+  /**
+   * secondaryAddress
+   *
+   * @method faker.address.secondaryAddress
+   */
   this.secondaryAddress = function () {
       return Helpers.replaceSymbolWithNumber(faker.random.arrayElement(
           [
@@ -94,30 +155,66 @@ function Address (faker) {
       ));
   }
 
+  /**
+   * county
+   *
+   * @method faker.address.county
+   */
   this.county = function () {
     return faker.random.arrayElement(faker.definitions.address.county);
   }
 
+  /**
+   * country
+   *
+   * @method faker.address.country
+   */
   this.country = function () {
     return faker.random.arrayElement(faker.definitions.address.country);
   }
 
+  /**
+   * countryCode
+   *
+   * @method faker.address.countryCode
+   */
   this.countryCode = function () {
     return faker.random.arrayElement(faker.definitions.address.country_code);
   }
 
+  /**
+   * state
+   *
+   * @method faker.address.state
+   * @param {Boolean} useAbbr
+   */
   this.state = function (useAbbr) {
       return faker.random.arrayElement(faker.definitions.address.state);
   }
 
+  /**
+   * stateAbbr
+   *
+   * @method faker.address.stateAbbr
+   */
   this.stateAbbr = function () {
       return faker.random.arrayElement(faker.definitions.address.state_abbr);
   }
 
+  /**
+   * latitude
+   *
+   * @method faker.address.latitude
+   */
   this.latitude = function () {
       return (faker.random.number(180 * 10000) / 10000.0 - 90.0).toFixed(4);
   }
 
+  /**
+   * longitude
+   *
+   * @method faker.address.longitude
+   */
   this.longitude = function () {
       return (faker.random.number(360 * 10000) / 10000.0 - 180.0).toFixed(4);
   }