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.

20 files changed, 910 insertions, 15 deletions

diff --git a/.gitignore b/.gitignore
index daa912ef..4a7cd83e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,3 +18,5 @@ node_modules/
 # meteor specific
 .build*
 versions.json
+
+doc/
diff --git a/Readme.md b/Readme.md
index 74315833..a3f77572 100644
--- a/Readme.md
+++ b/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
diff --git a/conf.json b/conf.json
new file mode 100644
index 00000000..1fd69e12
--- /dev/null
+++ b/conf.json
@@ -0,0 +1,9 @@
+{
+  "opts": {
+    "destination": "./doc/"
+  },
+
+  "plugins": [
+    "plugins/markdown"
+  ]
+}
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);
   }
diff --git a/lib/commerce.js b/lib/commerce.js
index ec91edb1..2c41455c 100644
--- a/lib/commerce.js
+++ b/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);
   }
diff --git a/lib/company.js b/lib/company.js
index f9fb0de3..ebb436dd 100644
--- a/lib/company.js
+++ b/lib/company.js
@@ -1,13 +1,28 @@
+/**
+ *
+ * @namespace faker.company
+ */
 var Company = function (faker) {
   
   var self = this;
   var f = faker.fake;
   
+  /**
+   * suffixes
+   *
+   * @method faker.company.suffixes
+   */
   this.suffixes = function () {
     // Don't want the source array exposed to modification, so return a copy
     return faker.definitions.company.suffix.slice(0);
   }
 
+  /**
+   * companyName
+   *
+   * @method faker.company.companyName
+   * @param {string} format
+   */
   this.companyName = function (format) {
 
     var formats = [
@@ -23,38 +38,83 @@ var Company = function (faker) {
     return f(formats[format]);
   }
 
+  /**
+   * companySuffix
+   *
+   * @method faker.company.companySuffix
+   */
   this.companySuffix = function () {
       return faker.random.arrayElement(faker.company.suffixes());
   }
 
+  /**
+   * catchPhrase
+   *
+   * @method faker.company.catchPhrase
+   */
   this.catchPhrase = function () {
     return f('{{company.catchPhraseAdjective}} {{company.catchPhraseDescriptor}} {{company.catchPhraseNoun}}')
   }
 
+  /**
+   * bs
+   *
+   * @method faker.company.bs
+   */
   this.bs = function () {
     return f('{{company.bsAdjective}} {{company.bsBuzz}} {{company.bsNoun}}');
   }
 
+  /**
+   * catchPhraseAdjective
+   *
+   * @method faker.company.catchPhraseAdjective
+   */
   this.catchPhraseAdjective = function () {
       return faker.random.arrayElement(faker.definitions.company.adjective);
   }
 
+  /**
+   * catchPhraseDescriptor
+   *
+   * @method faker.company.catchPhraseDescriptor
+   */
   this.catchPhraseDescriptor = function () {
       return faker.random.arrayElement(faker.definitions.company.descriptor);
   }
 
+  /**
+   * catchPhraseNoun
+   *
+   * @method faker.company.catchPhraseNoun
+   */
   this.catchPhraseNoun = function () {
       return faker.random.arrayElement(faker.definitions.company.noun);
   }
 
+  /**
+   * bsAdjective
+   *
+   * @method faker.company.bsAdjective
+   */
   this.bsAdjective = function () {
       return faker.random.arrayElement(faker.definitions.company.bs_adjective);
   }
 
+  /**
+   * bsBuzz
+   *
+   * @method faker.company.bsBuzz
+   */
   this.bsBuzz = function () {
       return faker.random.arrayElement(faker.definitions.company.bs_verb);
   }
 
+  /**
+   * bsNoun
+   *
+   * @method faker.company.bsNoun
+   */
   this.bsNoun = function () {
       return faker.random.arrayElement(faker.definitions.company.bs_noun);
   }
diff --git a/lib/date.js b/lib/date.js
index 2c53a4e4..e1ce7a48 100644
--- a/lib/date.js
+++ b/lib/date.js
@@ -1,5 +1,16 @@
+/**
+ *
+ * @namespace faker.date
+ */
 var _Date = function (faker) {
   var self = this;
+  /**
+   * past
+   *
+   * @method faker.date.past
+   * @param {number} years
+   * @param {date} refDate
+   */
   self.past = function (years, refDate) {
       var date = (refDate) ? new Date(Date.parse(refDate)) : new Date();
       var range = {
@@ -14,6 +25,13 @@ var _Date = function (faker) {
       return date;
   };
 
+  /**
+   * future
+   *
+   * @method faker.date.future
+   * @param {number} years
+   * @param {date} refDate
+   */
   self.future = function (years, refDate) {
       var date = (refDate) ? new Date(Date.parse(refDate)) : new Date();
       var range = {
@@ -28,6 +46,13 @@ var _Date = function (faker) {
       return date;
   };
 
+  /**
+   * between
+   *
+   * @method faker.date.between
+   * @param {date} from
+   * @param {date} to
+   */
   self.between = function (from, to) {
       var fromMilli = Date.parse(from);
       var dateOffset = faker.random.number(Date.parse(to) - fromMilli);
@@ -37,6 +62,12 @@ var _Date = function (faker) {
       return newDate;
   };
 
+  /**
+   * recent
+   *
+   * @method faker.date.recent
+   * @param {number} days
+   */
   self.recent = function (days) {
       var date = new Date();
       var range = {
@@ -51,6 +82,12 @@ var _Date = function (faker) {
       return date;
   };
 
+  /**
+   * month
+   *
+   * @method faker.date.month
+   * @param {object} options
+   */
   self.month = function (options) {
       options = options || {};
 
@@ -67,6 +104,12 @@ var _Date = function (faker) {
       return faker.random.arrayElement(source);
   };
 
+  /**
+   * weekday
+   *
+   * @param {object} options
+   * @method faker.date.weekday
+   */
   self.weekday = function (options) {
       options = options || {};
 
diff --git a/lib/fake.js b/lib/fake.js
index a9072f74..977ba292 100644
--- a/lib/fake.js
+++ b/lib/fake.js
@@ -5,6 +5,23 @@
 
 function Fake (faker) {
   
+  /**
+   * Generator method for combining faker methods based on string input
+   *
+   * __Example:__
+   *
+   * ```
+   * console.log(faker.fake('{{name.lastName}}, {{name.firstName}} {{name.suffix}}'));
+   * //outputs: "Marks, Dean Sr."
+   * ```
+   *
+   * This will interpolate the format string with the value of methods
+   * [name.lastName]{@link faker.name.lastName}, [name.firstName]{@link faker.name.firstName},
+   * and [name.suffix]{@link faker.name.suffix}
+   *
+   * @method faker.fake
+   * @param {string} str
+   */
   this.fake = function fake (str) {
     // setup default response as empty string
     var res = '';
diff --git a/lib/finance.js b/lib/finance.js
index 0140cd19..4c6d92a6 100644
--- a/lib/finance.js
+++ b/lib/finance.js
@@ -1,7 +1,17 @@
+/**
+ *
+ * @namespace faker.finance
+ */
 var Finance = function (faker) {
   var Helpers = faker.helpers,
       self = this;
 
+  /**
+   * account
+   *
+   * @method faker.finance.account
+   * @param {number} length
+   */
   self.account = function (length) {
 
       length = length || 8;
@@ -15,11 +25,24 @@ var Finance = function (faker) {
       return Helpers.replaceSymbolWithNumber(template);
   }
 
+  /**
+   * accountName
+   *
+   * @method faker.finance.accountName
+   */
   self.accountName = function () {
 
       return [Helpers.randomize(faker.definitions.finance.account_type), 'Account'].join(' ');
   }
 
+  /**
+   * mask
+   *
+   * @method faker.finance.mask
+   * @param {number} length
+   * @param {boolean} parens
+   * @param {boolean} elipsis
+   */
   self.mask = function (length, parens, elipsis) {
 
 
@@ -50,6 +73,15 @@ var Finance = function (faker) {
   //min and max take in minimum and maximum amounts, dec is the decimal place you want rounded to, symbol is $, €, £, etc
   //NOTE: this returns a string representation of the value, if you want a number use parseFloat and no symbol
 
+  /**
+   * amount
+   *
+   * @method faker.finance.amount
+   * @param {number} min
+   * @param {number} max
+   * @param {number} dec
+   * @param {string} symbol
+   */
   self.amount = function (min, max, dec, symbol) {
 
       min = min || 0;
@@ -61,18 +93,38 @@ var Finance = function (faker) {
 
   }
 
+  /**
+   * transactionType
+   *
+   * @method faker.finance.transactionType
+   */
   self.transactionType = function () {
       return Helpers.randomize(faker.definitions.finance.transaction_type);
   }
 
+  /**
+   * currencyCode
+   *
+   * @method faker.finance.currencyCode
+   */
   self.currencyCode = function () {
       return faker.random.objectElement(faker.definitions.finance.currency)['code'];
   }
 
+  /**
+   * currencyName
+   *
+   * @method faker.finance.currencyName
+   */
   self.currencyName = function () {
       return faker.random.objectElement(faker.definitions.finance.currency, 'key');
   }
 
+  /**
+   * currencySymbol
+   *
+   * @method faker.finance.currencySymbol
+   */
   self.currencySymbol = function () {
       var symbol;
 
diff --git a/lib/hacker.js b/lib/hacker.js
index 463f8331..c87a8d28 100644
--- a/lib/hacker.js
+++ b/lib/hacker.js
@@ -1,26 +1,60 @@
+/**
+ *
+ * @namespace faker.hacker
+ */
 var Hacker = function (faker) {
   var self = this;
   
+  /**
+   * abbreviation
+   *
+   * @method faker.hacker.abbreviation
+   */
   self.abbreviation = function () {
     return faker.random.arrayElement(faker.definitions.hacker.abbreviation);
   };
 
+  /**
+   * adjective
+   *
+   * @method faker.hacker.adjective
+   */
   self.adjective = function () {
     return faker.random.arrayElement(faker.definitions.hacker.adjective);
   };
 
+  /**
+   * noun
+   *
+   * @method faker.hacker.noun
+   */
   self.noun = function () {
     return faker.random.arrayElement(faker.definitions.hacker.noun);
   };
 
+  /**
+   * verb
+   *
+   * @method faker.hacker.verb
+   */
   self.verb = function () {
     return faker.random.arrayElement(faker.definitions.hacker.verb);
   };
 
+  /**
+   * ingverb
+   *
+   * @method faker.hacker.ingverb
+   */
   self.ingverb = function () {
     return faker.random.arrayElement(faker.definitions.hacker.ingverb);
   };
 
+  /**
+   * phrase
+   *
+   * @method faker.hacker.phrase
+   */
   self.phrase = function () {
 
     var data = {
diff --git a/lib/helpers.js b/lib/helpers.js
index ec8e1573..6434baa3 100644
--- a/lib/helpers.js
+++ b/lib/helpers.js
@@ -1,20 +1,40 @@
+/**
+ *
+ * @namespace faker.helpers
+ */
 var Helpers = function (faker) {
 
   var self = this;
 
-  // backword-compatibility
+  /**
+   * backword-compatibility
+   *
+   * @method faker.helpers.randomize
+   * @param {array} array
+   */
   self.randomize = function (array) {
       array = array || ["a", "b", "c"];
       return faker.random.arrayElement(array);
   };
 
-  // slugifies string
+  /**
+   * slugifies string
+   *
+   * @method faker.helpers.slugify
+   * @param {string} string
+   */
   self.slugify = function (string) {
       string = string || "";
       return string.replace(/ /g, '-').replace(/[^\w\.\-]+/g, '');
   };
 
-  // parses string for a symbol and replace it with a random number from 1-10
+  /**
+   * parses string for a symbol and replace it with a random number from 1-10
+   *
+   * @method faker.helpers.replaceSymbolWithNumber
+   * @param {string} string
+   * @param {string} symbol defaults to `"#"`
+   */
   self.replaceSymbolWithNumber = function (string, symbol) {
       string = string || "";
       // default symbol is '#'
@@ -33,7 +53,12 @@ var Helpers = function (faker) {
       return str;
   };
 
-  // parses string for symbols (numbers or letters) and replaces them appropriately
+  /**
+   * parses string for symbols (numbers or letters) and replaces them appropriately
+   *
+   * @method faker.helpers.replaceSymbols
+   * @param {string} string
+   */
   self.replaceSymbols = function (string) {
       string = string || "";
   	var alpha = ['A','B','C','D','E','F','G','H','I','J','K','L','M','N','O','P','Q','R','S','T','U','V','W','X','Y','Z']
@@ -51,13 +76,25 @@ var Helpers = function (faker) {
       return str;
   };
 
-  // takes an array and returns it randomized
+  /**
+   * takes an array and returns it randomized
+   *
+   * @method faker.helpers.shuffle
+   * @param {array} o
+   */
   self.shuffle = function (o) {
       o = o || ["a", "b", "c"];
       for (var j, x, i = o.length-1; i; j = faker.random.number(i), x = o[--i], o[i] = o[j], o[j] = x);
       return o;
   };
 
+  /**
+   * mustache
+   *
+   * @method faker.helpers.mustache
+   * @param {string} str
+   * @param {object} data
+   */
   self.mustache = function (str, data) {
     if (typeof str === 'undefined') {
       return '';
@@ -69,6 +106,11 @@ var Helpers = function (faker) {
     return str;
   };
 
+  /**
+   * createCard
+   *
+   * @method faker.helpers.createCard
+   */
   self.createCard = function () {
       return {
           "name": faker.name.findName(),
@@ -119,6 +161,11 @@ var Helpers = function (faker) {
       };
   };
 
+  /**
+   * contextualCard
+   *
+   * @method faker.helpers.contextualCard
+   */
   self.contextualCard = function () {
     var name = faker.name.firstName(),
         userName = faker.internet.userName(name);
@@ -149,6 +196,11 @@ var Helpers = function (faker) {
   };
 
 
+  /**
+   * userCard
+   *
+   * @method faker.helpers.userCard
+   */
   self.userCard = function () {
       return {
           "name": faker.name.findName(),
@@ -174,6 +226,11 @@ var Helpers = function (faker) {
       };
   };
 
+  /**
+   * createTransaction
+   *
+   * @method faker.helpers.createTransaction
+   */
   self.createTransaction = function(){
     return {
       "amount" : faker.finance.amount(),
diff --git a/lib/image.js b/lib/image.js
index 5479f349..20576d92 100644
--- a/lib/image.js
+++ b/lib/image.js
@@ -1,14 +1,40 @@
+/**
+ *
+ * @namespace faker.image
+ */
 var Image = function (faker) {
 
   var self = this;
 
+  /**
+   * image
+   *
+   * @param {number} width
+   * @param {number} height
+   * @param {boolean} randomize
+   * @method faker.image.image
+   */
   self.image = function (width, height, randomize) {
     var categories = ["abstract", "animals", "business", "cats", "city", "food", "nightlife", "fashion", "people", "nature", "sports", "technics", "transport"];
     return self[faker.random.arrayElement(categories)](width, height, randomize);
   };
+  /**
+   * avatar
+   *
+   * @method faker.image.avatar
+   */
   self.avatar = function () {
     return faker.internet.avatar();
   };
+  /**
+   * imageUrl
+   *
+   * @param {number} width
+   * @param {number} height
+   * @param {string} category
+   * @param {boolean} randomize
+   * @method faker.image.imageUrl
+   */
   self.imageUrl = function (width, height, category, randomize) {
       var width = width || 640;
       var height = height || 480;
@@ -24,42 +50,146 @@ var Image = function (faker) {
 
       return url;
   };
+  /**
+   * abstract
+   *
+   * @param {number} width
+   * @param {number} height
+   * @param {boolean} randomize
+   * @method faker.image.abstract
+   */
   self.abstract = function (width, height, randomize) {
     return faker.image.imageUrl(width, height, 'abstract', randomize);
   };
+  /**
+   * animals
+   *
+   * @param {number} width
+   * @param {number} height
+   * @param {boolean} randomize
+   * @method faker.image.animals
+   */
   self.animals = function (width, height, randomize) {
     return faker.image.imageUrl(width, height, 'animals', randomize);
   };
+  /**
+   * business
+   *
+   * @param {number} width
+   * @param {number} height
+   * @param {boolean} randomize
+   * @method faker.image.business
+   */
   self.business = function (width, height, randomize) {
     return faker.image.imageUrl(width, height, 'business', randomize);
   };
+  /**
+   * cats
+   *
+   * @param {number} width
+   * @param {number} height
+   * @param {boolean} randomize
+   * @method faker.image.cats
+   */
   self.cats = function (width, height, randomize) {
     return faker.image.imageUrl(width, height, 'cats', randomize);
   };
+  /**
+   * city
+   *
+   * @param {number} width
+   * @param {number} height
+   * @param {boolean} randomize
+   * @method faker.image.city
+   */
   self.city = function (width, height, randomize) {
     return faker.image.imageUrl(width, height, 'city', randomize);
   };
+  /**
+   * food
+   *
+   * @param {number} width
+   * @param {number} height
+   * @param {boolean} randomize
+   * @method faker.image.food
+   */
   self.food = function (width, height, randomize) {
     return faker.image.imageUrl(width, height, 'food', randomize);
   };
+  /**
+   * nightlife
+   *
+   * @param {number} width
+   * @param {number} height
+   * @param {boolean} randomize
+   * @method faker.image.nightlife
+   */
   self.nightlife = function (width, height, randomize) {
     return faker.image.imageUrl(width, height, 'nightlife', randomize);
   };
+  /**
+   * fashion
+   *
+   * @param {number} width
+   * @param {number} height
+   * @param {boolean} randomize
+   * @method faker.image.fashion
+   */
   self.fashion = function (width, height, randomize) {
     return faker.image.imageUrl(width, height, 'fashion', randomize);
   };
+  /**
+   * people
+   *
+   * @param {number} width
+   * @param {number} height
+   * @param {boolean} randomize
+   * @method faker.image.people
+   */
   self.people = function (width, height, randomize) {
     return faker.image.imageUrl(width, height, 'people', randomize);
   };
+  /**
+   * nature
+   *
+   * @param {number} width
+   * @param {number} height
+   * @param {boolean} randomize
+   * @method faker.image.nature
+   */
   self.nature = function (width, height, randomize) {
     return faker.image.imageUrl(width, height, 'nature', randomize);
   };
+  /**
+   * sports
+   *
+   * @param {number} width
+   * @param {number} height
+   * @param {boolean} randomize
+   * @method faker.image.sports
+   */
   self.sports = function (width, height, randomize) {
     return faker.image.imageUrl(width, height, 'sports', randomize);
   };
+  /**
+   * technics
+   *
+   * @param {number} width
+   * @param {number} height
+   * @param {boolean} randomize
+   * @method faker.image.technics
+   */
   self.technics = function (width, height, randomize) {
     return faker.image.imageUrl(width, height, 'technics', randomize);
   };
+  /**
+   * transport
+   *
+   * @param {number} width
+   * @param {number} height
+   * @param {boolean} randomize
+   * @method faker.image.transport
+   */
   self.transport = function (width, height, randomize) {
     return faker.image.imageUrl(width, height, 'transport', randomize);
   }  
diff --git a/lib/index.js b/lib/index.js
index 5fe97d77..ed0a664b 100644
--- a/lib/index.js
+++ b/lib/index.js
@@ -17,6 +17,10 @@
 
 */
 
+/**
+ *
+ * @namespace faker
+ */
 function Faker (opts) {
 
   var self = this;
diff --git a/lib/internet.js b/lib/internet.js
index 980703af..4996ac87 100644
--- a/lib/internet.js
+++ b/lib/internet.js
@@ -1,8 +1,17 @@
 var password_generator = require('../vendor/password-generator.js'),
     random_ua = require('../vendor/user-agent');
 
+/**
+ *
+ * @namespace faker.internet
+ */
 var Internet = function (faker) {
   var self = this;
+  /**
+   * avatar
+   *
+   * @method faker.internet.avatar
+   */
   self.avatar = function () {
       return faker.random.arrayElement(faker.definitions.internet.avatar_uri);
   };
@@ -12,6 +21,14 @@ var Internet = function (faker) {
     "sampleResults": ["https://s3.amazonaws.com/uifaces/faces/twitter/igorgarybaldi/128.jpg"]
   };
 
+  /**
+   * email
+   *
+   * @method faker.internet.email
+   * @param {string} firstName
+   * @param {string} lastName
+   * @param {string} provider
+   */
   self.email = function (firstName, lastName, provider) {
       provider = provider || faker.random.arrayElement(faker.definitions.internet.free_email);
       return  faker.helpers.slugify(faker.internet.userName(firstName, lastName)) + "@" + provider;
@@ -38,11 +55,25 @@ var Internet = function (faker) {
       }
     }
   };
+  /**
+   * exampleEmail
+   *
+   * @method faker.internet.exampleEmail
+   * @param {string} firstName
+   * @param {string} lastName
+   */
   self.exampleEmail = function (firstName, lastName) {
       var provider = faker.random.arrayElement(faker.definitions.internet.example_email);
       return this.email(firstName, lastName, provider);
   };
 
+  /**
+   * userName
+   *
+   * @method faker.internet.userName
+   * @param {string} firstName
+   * @param {string} lastName
+   */
   self.userName = function (firstName, lastName) {
       var result;
       firstName = firstName || faker.name.firstName();
@@ -86,6 +117,11 @@ var Internet = function (faker) {
     }
   };
 
+  /**
+   * protocol
+   *
+   * @method faker.internet.protocol
+   */
   self.protocol = function () {
       var protocols = ['http','https'];
       return faker.random.arrayElement(protocols);
@@ -96,6 +132,11 @@ var Internet = function (faker) {
     "sampleResults": ["https", "http"]
   };
 
+  /**
+   * url
+   *
+   * @method faker.internet.url
+   */
   self.url = function () {
       return faker.internet.protocol() + '://' + faker.internet.domainName();
   };
@@ -108,6 +149,11 @@ var Internet = function (faker) {
     ]
   };
 
+  /**
+   * domainName
+   *
+   * @method faker.internet.domainName
+   */
   self.domainName = function () {
       return faker.internet.domainWord() + "." + faker.internet.domainSuffix();
   };
@@ -117,6 +163,11 @@ var Internet = function (faker) {
     "sampleResults": ["marvin.org"]
   };
 
+  /**
+   * domainSuffix
+   *
+   * @method faker.internet.domainSuffix
+   */
   self.domainSuffix = function () {
       return faker.random.arrayElement(faker.definitions.internet.domain_suffix);
   };
@@ -126,6 +177,11 @@ var Internet = function (faker) {
     "sampleResults": ["net"]
   };
 
+  /**
+   * domainWord
+   *
+   * @method faker.internet.domainWord
+   */
   self.domainWord = function () {
       return faker.name.firstName().replace(/([\\~#&*{}/:<>?|\"'])/ig, '').toLowerCase();
   };
@@ -135,6 +191,11 @@ var Internet = function (faker) {
     "sampleResults": ["alyce"]
   };
 
+  /**
+   * ip
+   *
+   * @method faker.internet.ip
+   */
   self.ip = function () {
       var randNum = function () {
           return (faker.random.number(255)).toFixed(0);
@@ -153,6 +214,11 @@ var Internet = function (faker) {
     "sampleResults": ["97.238.241.11"]
   };
 
+  /**
+   * userAgent
+   *
+   * @method faker.internet.userAgent
+   */
   self.userAgent = function () {
     return random_ua.generate();
   };
@@ -162,6 +228,14 @@ var Internet = function (faker) {
     "sampleResults": ["Mozilla/5.0 (Macintosh; U; PPC Mac OS X 10_7_5 rv:6.0; SL) AppleWebKit/532.0.1 (KHTML, like Gecko) Version/7.1.6 Safari/532.0.1"]
   };
 
+  /**
+   * color
+   *
+   * @method faker.internet.color
+   * @param {number} baseRed255
+   * @param {number} baseGreen255
+   * @param {number} baseBlue255
+   */
   self.color = function (baseRed255, baseGreen255, baseBlue255) {
       baseRed255 = baseRed255 || 0;
       baseGreen255 = baseGreen255 || 0;
@@ -202,6 +276,11 @@ var Internet = function (faker) {
     }
   };
 
+  /**
+   * mac
+   *
+   * @method faker.internet.mac
+   */
   self.mac = function(){
       var i, mac = "";
       for (i=0; i < 12; i++) {
@@ -218,6 +297,15 @@ var Internet = function (faker) {
     "sampleResults": ["78:06:cc:ae:b3:81"]
   };
 
+  /**
+   * password
+   *
+   * @method faker.internet.password
+   * @param {number} len
+   * @param {boolean} memorable
+   * @param {string} pattern
+   * @param {string} prefix
+   */
   self.password = function (len, memorable, pattern, prefix) {
     len = len || 15;
     if (typeof memorable === "undefined") {
diff --git a/lib/lorem.js b/lib/lorem.js
index 189bbba0..46b5ae22 100644
--- a/lib/lorem.js
+++ b/lib/lorem.js
@@ -1,12 +1,28 @@
 
+/**
+ *
+ * @namespace faker.lorem
+ */
 var Lorem = function (faker) {
   var self = this;
   var Helpers = faker.helpers;
 
+  /**
+   * word
+   *
+   * @method faker.lorem.word
+   * @param {number} num
+   */
   self.word = function (num) {
     return faker.random.arrayElement(faker.definitions.lorem.words);
   };
 
+  /**
+   * generates a space separated list of words
+   *
+   * @method faker.lorem.words
+   * @param {number} num number of words, defaults to 3
+   */
   self.words = function (num) {
       if (typeof num == 'undefined') { num = 3; }
       var words = [];
@@ -16,6 +32,13 @@ var Lorem = function (faker) {
       return words.join(' ');
   };
 
+  /**
+   * sentence
+   *
+   * @method faker.lorem.sentence
+   * @param {number} wordCount defaults to a random number between 3 and 10
+   * @param {number} range
+   */
   self.sentence = function (wordCount, range) {
       if (typeof wordCount == 'undefined') { wordCount = faker.random.number({ min: 3, max: 10 }); }
       // if (typeof range == 'undefined') { range = 7; }
@@ -27,6 +50,13 @@ var Lorem = function (faker) {
       return sentence.charAt(0).toUpperCase() + sentence.slice(1) + '.';
   };
 
+  /**
+   * sentences
+   *
+   * @method faker.lorem.sentences
+   * @param {number} sentenceCount defautls to a random number between 2 and 6
+   * @param {string} separator defaults to `' '`
+   */
   self.sentences = function (sentenceCount, separator) {
       if (typeof sentenceCount === 'undefined') { sentenceCount = faker.random.number({ min: 2, max: 6 });}
       if (typeof separator == 'undefined') { separator = " "; }
@@ -37,11 +67,24 @@ var Lorem = function (faker) {
       return sentences.join(separator);
   };
 
+  /**
+   * paragraph
+   *
+   * @method faker.lorem.paragraph
+   * @param {number} sentenceCount defaults to 3
+   */
   self.paragraph = function (sentenceCount) {
       if (typeof sentenceCount == 'undefined') { sentenceCount = 3; }
       return faker.lorem.sentences(sentenceCount + faker.random.number(3));
   };
 
+  /**
+   * paragraphs
+   *
+   * @method faker.lorem.paragraphs
+   * @param {number} paragraphCount defaults to 3
+   * @param {string} separatora defaults to `'\n \r'`
+   */
   self.paragraphs = function (paragraphCount, separator) {
     if (typeof separator === "undefined") {
       separator = "\n \r";
@@ -54,14 +97,24 @@ var Lorem = function (faker) {
     return paragraphs.join(separator);
   }
 
-  // returns random text based on a random lorem method
+  /**
+   * returns random text based on a random lorem method
+   *
+   * @method faker.lorem.text
+   * @param {number} times
+   */
   self.text = function loremText (times) {
     var loremMethods = ['lorem.word', 'lorem.words', 'lorem.sentence', 'lorem.sentences', 'lorem.paragraph', 'lorem.paragraphs', 'lorem.lines'];
     var randomLoremMethod = faker.random.arrayElement(loremMethods);
     return faker.fake('{{' + randomLoremMethod + '}}');
   };
 
-  // returns lines of lorem separated by \n
+  /**
+   * returns lines of lorem separated by `'\n'`
+   *
+   * @method faker.lorem.lines
+   * @param {number} lineCount defaults to a random number between 1 and 5
+   */
   self.lines = function lines (lineCount) {
     if (typeof lineCount === 'undefined') { lineCount = faker.random.number({ min: 1, max: 5 });}
     return faker.lorem.sentences(lineCount, '\n')
diff --git a/lib/name.js b/lib/name.js
index 83793045..3280341c 100644
--- a/lib/name.js
+++ b/lib/name.js
@@ -1,5 +1,16 @@
+/**
+ *
+ * @namespace faker.name
+ */
 function Name (faker) {
 
+  /**
+   * firstName
+   *
+   * @method firstName
+   * @param {mixed} gender
+   * @memberof faker.name
+   */
   this.firstName = function (gender) {
     if (typeof faker.definitions.name.male_first_name !== "undefined" && typeof faker.definitions.name.female_first_name !== "undefined") {
       // some locale datasets ( like ru ) have first_name split by gender. since the name.first_name field does not exist in these datasets,
@@ -16,6 +27,13 @@ function Name (faker) {
     return faker.random.arrayElement(faker.definitions.name.first_name);
   };
 
+  /**
+   * lastName
+   *
+   * @method lastName
+   * @param {mixed} gender
+   * @memberof faker.name
+   */
   this.lastName = function (gender) {
     if (typeof faker.definitions.name.male_last_name !== "undefined" && typeof faker.definitions.name.female_last_name !== "undefined") {
       // some locale datasets ( like ru ) have last_name split by gender. i have no idea how last names can have genders, but also i do not speak russian
@@ -32,6 +50,15 @@ function Name (faker) {
     return faker.random.arrayElement(faker.definitions.name.last_name);
   };
 
+  /**
+   * findName
+   *
+   * @method findName
+   * @param {string} firstName
+   * @param {string} lastName
+   * @param {mixed} gender
+   * @memberof faker.name
+   */
   this.findName = function (firstName, lastName, gender) {
       var r = faker.random.number(8);
       var prefix, suffix;
@@ -58,12 +85,25 @@ function Name (faker) {
       return firstName + " " + lastName;
   };
 
+  /**
+   * jobTitle
+   *
+   * @method jobTitle
+   * @memberof faker.name
+   */
   this.jobTitle = function () {
     return  faker.name.jobDescriptor() + " " +
       faker.name.jobArea() + " " +
       faker.name.jobType();
   };
   
+  /**
+   * prefix
+   *
+   * @method prefix
+   * @param {mixed} gender
+   * @memberof faker.name
+   */
   this.prefix = function (gender) {
     if (typeof faker.definitions.name.male_prefix !== "undefined" && typeof faker.definitions.name.female_prefix !== "undefined") {
       if (typeof gender !== 'number') {
@@ -78,10 +118,22 @@ function Name (faker) {
     return faker.random.arrayElement(faker.definitions.name.prefix);
   };
 
+  /**
+   * suffix
+   *
+   * @method suffix
+   * @memberof faker.name
+   */
   this.suffix = function () {
       return faker.random.arrayElement(faker.definitions.name.suffix);
   };
 
+  /**
+   * title
+   *
+   * @method title
+   * @memberof faker.name
+   */
   this.title = function() {
       var descriptor  = faker.random.arrayElement(faker.definitions.name.title.descriptor),
           level       = faker.random.arrayElement(faker.definitions.name.title.level),
@@ -90,14 +142,32 @@ function Name (faker) {
       return descriptor + " " + level + " " + job;
   };
 
+  /**
+   * jobDescriptor
+   *
+   * @method jobDescriptor
+   * @memberof faker.name
+   */
   this.jobDescriptor = function () {
     return faker.random.arrayElement(faker.definitions.name.title.descriptor);
   };
 
+  /**
+   * jobArea
+   *
+   * @method jobArea
+   * @memberof faker.name
+   */
   this.jobArea = function () {
     return faker.random.arrayElement(faker.definitions.name.title.level);
   };
 
+  /**
+   * jobType
+   *
+   * @method jobType
+   * @memberof faker.name
+   */
   this.jobType = function () {
     return faker.random.arrayElement(faker.definitions.name.title.job);
   };
diff --git a/lib/phone_number.js b/lib/phone_number.js
index 4489ea22..651c7ada 100644
--- a/lib/phone_number.js
+++ b/lib/phone_number.js
@@ -1,17 +1,38 @@
+/**
+ *
+ * @namespace faker.phone
+ */
 var Phone = function (faker) {
   var self = this;
 
+  /**
+   * phoneNumber
+   *
+   * @method faker.phone.phoneNumber
+   * @param {string} format
+   */
   self.phoneNumber = function (format) {
       format = format || faker.phone.phoneFormats();
       return faker.helpers.replaceSymbolWithNumber(format);
   };
 
   // FIXME: this is strange passing in an array index.
+  /**
+   * phoneNumberFormat
+   *
+   * @method faker.phone.phoneFormatsArrayIndex
+   * @param phoneFormatsArrayIndex
+   */
   self.phoneNumberFormat = function (phoneFormatsArrayIndex) {
       phoneFormatsArrayIndex = phoneFormatsArrayIndex || 0;
       return faker.helpers.replaceSymbolWithNumber(faker.definitions.phone_number.formats[phoneFormatsArrayIndex]);
   };
 
+  /**
+   * phoneFormats
+   *
+   * @method faker.phone.phoneFormats
+   */
   self.phoneFormats = function () {
     return faker.random.arrayElement(faker.definitions.phone_number.formats);
   };
diff --git a/lib/random.js b/lib/random.js
index 138d4bdc..b152ddbd 100644
--- a/lib/random.js
+++ b/lib/random.js
@@ -1,5 +1,9 @@
 var mersenne = require('../vendor/mersenne');
 
+/**
+ *
+ * @namespace faker.random
+ */
 function Random (faker, seed) {
   // Use a user provided seed if it exists
   if (seed) {
@@ -10,7 +14,12 @@ function Random (faker, seed) {
       mersenne.seed(seed);
     }
   }
-  // returns a single random number based on a max number or range
+  /**
+   * returns a single random number based on a max number or range
+   *
+   * @method faker.random.number
+   * @param {mixed} options
+   */
   this.number = function (options) {
 
     if (typeof options === "number") {
@@ -45,14 +54,25 @@ function Random (faker, seed) {
 
   }
 
-  // takes an array and returns a random element of the array
+  /**
+   * takes an array and returns a random element of the array
+   *
+   * @method faker.random.arrayElement
+   * @param {array} array
+   */
   this.arrayElement = function (array) {
       array = array || ["a", "b", "c"];
       var r = faker.random.number({ max: array.length - 1 });
       return array[r];
   }
 
-  // takes an object and returns the randomly key or value
+  /**
+   * takes an object and returns the randomly key or value
+   *
+   * @method faker.random.objectElement
+   * @param {object} object
+   * @param {mixed} field
+   */
   this.objectElement = function (object, field) {
       object = object || { "foo": "bar", "too": "car" };
       var array = Object.keys(object);
@@ -61,6 +81,11 @@ function Random (faker, seed) {
       return field === "key" ? key : object[key];
   }
 
+  /**
+   * uuid
+   *
+   * @method faker.random.uuid
+   */
   this.uuid = function () {
       var self = this;
       var RFC4122_TEMPLATE = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx';
@@ -72,11 +97,22 @@ function Random (faker, seed) {
       return RFC4122_TEMPLATE.replace(/[xy]/g, replacePlaceholders);
   }
 
+  /**
+   * boolean
+   *
+   * @method faker.random.boolean
+   */
   this.boolean = function () {
       return !!faker.random.number(1)
   }
 
   // TODO: have ability to return specific type of word? As in: noun, adjective, verb, etc
+  /**
+   * word
+   *
+   * @method faker.random.word
+   * @param {string} type
+   */
   this.word = function randomWord (type) {
 
     var wordMethods = [
@@ -118,6 +154,12 @@ function Random (faker, seed) {
 
   }
 
+  /**
+   * randomWords
+   *
+   * @method faker.random.words
+   * @param {number} count defaults to a random value between 1 and 3
+   */
   this.words = function randomWords (count) {
     var words = [];
     if (typeof count === "undefined") {
@@ -129,10 +171,20 @@ function Random (faker, seed) {
     return words.join(' ');
   }
 
+  /**
+   * locale
+   *
+   * @method faker.random.image
+   */
   this.image = function randomImage () {
     return faker.image.image();
   }
 
+  /**
+   * locale
+   *
+   * @method faker.random.locale
+   */
   this.locale = function randomLocale () {
     return faker.random.arrayElement(Object.keys(faker.locales));
   };
diff --git a/lib/system.js b/lib/system.js
index 0ecb94bc..60a55246 100644
--- a/lib/system.js
+++ b/lib/system.js
@@ -1,8 +1,18 @@
 // generates fake data for many computer systems properties
 
+/**
+ *
+ * @namespace faker.system
+ */
 function System (faker) {
 
-  // generates a file name with extension or optional type
+  /**
+   * generates a file name with extension or optional type
+   *
+   * @method faker.system.fileName
+   * @param {string} ext
+   * @param {string} type
+   */
   this.fileName = function (ext, type) {
     var str = faker.fake("{{random.words}}.{{system.fileExt}}");
     str = str.replace(/ /g, '_');
@@ -13,6 +23,13 @@ function System (faker) {
     return str;
   };
 
+  /**
+   * commonFileName
+   *
+   * @method faker.system.commonFileName
+   * @param {string} ext
+   * @param {string} type
+   */
   this.commonFileName = function (ext, type) {
     var str = faker.random.words() + "." + (ext || faker.system.commonFileExt());
     str = str.replace(/ /g, '_');
@@ -23,17 +40,31 @@ function System (faker) {
     return str;
   };
 
+  /**
+   * mimeType
+   *
+   * @method faker.system.mimeType
+   */
   this.mimeType = function () {
     return faker.random.arrayElement(Object.keys(faker.definitions.system.mimeTypes));
   };
 
-  // returns a commonly used file type
+  /**
+   * returns a commonly used file type
+   *
+   * @method faker.system.commonFileType
+   */
   this.commonFileType = function () {
     var types = ['video', 'audio', 'image', 'text', 'application'];
     return faker.random.arrayElement(types)
   };
 
-  // returns a commonly used file extension based on optional type
+  /**
+   * returns a commonly used file extension based on optional type
+   *
+   * @method faker.system.commonFileExt
+   * @param {string} type
+   */
   this.commonFileExt = function (type) {
     var types = [
       'application/pdf',
@@ -50,7 +81,11 @@ function System (faker) {
   };
 
 
-  // returns any file type available as mime-type
+  /**
+   * returns any file type available as mime-type
+   *
+   * @method faker.system.fileType
+   */
   this.fileType = function () {
     var types = [];
     var mimes = faker.definitions.system.mimeTypes;
@@ -63,6 +98,12 @@ function System (faker) {
     return faker.random.arrayElement(types);
   };
 
+  /**
+   * fileExt
+   *
+   * @method faker.system.fileExt
+   * @param {string} mimeType
+   */
   this.fileExt = function (mimeType) {
     var exts = [];
     var mimes = faker.definitions.system.mimeTypes;
@@ -83,14 +124,29 @@ function System (faker) {
     return faker.random.arrayElement(exts);
   };
 
+  /**
+   * not yet implemented
+   *
+   * @method faker.system.directoryPath
+   */
   this.directoryPath = function () {
     // TODO
   };
 
+  /**
+   * not yet implemented
+   *
+   * @method faker.system.filePath
+   */
   this.filePath = function () {
     // TODO
   };
 
+  /**
+   * semver
+   *
+   * @method faker.system.semver
+   */
   this.semver = function () {
       return [faker.random.number(9),
               faker.random.number(9),
diff --git a/package.json b/package.json
index e18a7533..9093e1e7 100644
--- a/package.json
+++ b/package.json
@@ -13,7 +13,8 @@
   "scripts": {
     "lint": "node_modules/.bin/jshint ./lib --config ./.jshintrc",
     "test": "node_modules/.bin/mocha test/*.*.js",
-    "build": "cd build && ../node_modules/.bin/gulp && cd ../"
+    "build": "cd build && ../node_modules/.bin/gulp && cd ../",
+    "doc": "jsdoc -c conf.json -t ./node_modules/ink-docstrap/template -R README.md lib"
   },
   "devDependencies": {
     "browserify": "5.11.1",
@@ -21,6 +22,7 @@
     "gulp-mustache": "0.4.0",
     "gulp-rename": "1.2.0",
     "gulp-uglify": "1.0.1",
+    "jsdoc": "^3.4.0",
     "jshint": "0.9.0",
     "lodash": "^2.4.1",
     "mocha": "1.8.x",