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.

.gitignore

@@ -18,3 +18,5 @@ node_modules/
 # meteor specific
 .build*
 versions.json
+
+doc/

Readme.md

@@ -58,6 +58,9 @@ This will interpolate the format string with the value of methods `name.lastName
 
 ### API Methods
 
+A documentation can be generated with `npm run-script doc`. The docs are put into `./doc`. Here is
+an overview of all api methods:
+
 * address
   * zipCode
   * city

conf.json

@@ -0,0 +1,9 @@
+{
+  "opts": {
+    "destination": "./doc/"
+  },
+
+  "plugins": [
+    "plugins/markdown"
+  ]
+}

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);
   }

lib/commerce.js

@@ -1,10 +1,26 @@
+/**
+ *
+ * @namespace faker.commerce
+ */
 var Commerce = function (faker) {
   var self = this;
 
+  /**
+   * color
+   *
+   * @method faker.commerce.color
+   */
   self.color = function() {
       return faker.random.arrayElement(faker.definitions.commerce.color);
   };
 
+  /**
+   * department
+   *
+   * @method faker.commerce.department
+   * @param {number} max
+   * @param {number} fixedAmount
+   */
   self.department = function(max, fixedAmount) {
 
       return faker.random.arrayElement(faker.definitions.commerce.department);
@@ -26,12 +42,26 @@ var Commerce = function (faker) {
       */
   };
 
+  /**
+   * productName
+   *
+   * @method faker.commerce.productName
+   */
   self.productName = function() {
       return faker.commerce.productAdjective() + " " +
               faker.commerce.productMaterial() + " " +
               faker.commerce.product();
   };
 
+  /**
+   * price
+   *
+   * @method faker.commerce.price
+   * @param {number} min
+   * @param {number} max
+   * @param {number} dec
+   * @param {string} symbol
+   */
   self.price = function(min, max, dec, symbol) {
       min = min || 0;
       max = max || 1000;
@@ -71,14 +101,29 @@ var Commerce = function (faker) {
   };
   */
 
+  /**
+   * productAdjective
+   *
+   * @method faker.commerce.productAdjective
+   */
   self.productAdjective = function() {
       return faker.random.arrayElement(faker.definitions.commerce.product_name.adjective);
   };
 
+  /**
+   * productMaterial
+   *
+   * @method faker.commerce.productMaterial
+   */
   self.productMaterial = function() {
       return faker.random.arrayElement(faker.definitions.commerce.product_name.material);
   };
 
+  /**
+   * product
+   *
+   * @method faker.commerce.product
+   */
   self.product = function() {
       return faker.random.arrayElement(faker.definitions.commerce.product_name.product);
   }