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, 55 insertions, 3 deletions

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