Updated comments to include JSDoc fields

1 files changed, 77 insertions, 36 deletions

diff --git a/lib/word.js b/lib/word.js
index 7a34b9f8..0040ae4a 100644
--- a/lib/word.js
+++ b/lib/word.js
@@ -1,15 +1,15 @@
 /**
- *
  * @namespace faker.word
  */
 var Word = function (faker) {
   var self = this;
   /**
-   * returns an adjective
+   * Returns an adjective of random or optionally specified length.
+   * If specified length is unresolvable, returns random adjective.
    *
-   * @method faker.adjective
-   * @param {number} [length] - optional length of word to return. Returns
-   *                            stringified 'undefined' if unable to meet criteria.
+   * @method faker.word.adjective
+   * @param {number} [length] - optional length of word to return
+   * @returns {string}          a random adjective
    */
   self.adjective = function (length) {
     var wordList = faker.definitions.word.adjective;
@@ -19,14 +19,20 @@ var Word = function (faker) {
         return word.length == length;
       });
     }
-    return faker.random.arrayElement(wordList) || "undefined";
+    // If result of filtered word list is undefined, return an element
+    // from the unfiltered list.
+    return (
+      faker.random.arrayElement(wordList) ||
+      faker.random.arrayElement(faker.definitions.word.adjective)
+    );
   };
   /**
-   * returns an adverb
+   * Returns an adverb of random or optionally specified length.
+   * If specified length is unresolvable, returns random adverb.
    *
-   * @method faker.adverb
-   * @param {number} [length] - optional length of word to return. Returns
-   *                            stringified 'undefined' if unable to meet criteria.
+   * @method faker.word.adverb
+   * @param {number} [length] - optional length of word to return
+   * @returns {string}          random adverb
    */
   self.adverb = function (length) {
     var wordList = faker.definitions.word.adverb;
@@ -36,14 +42,20 @@ var Word = function (faker) {
         return word.length == length;
       });
     }
-    return faker.random.arrayElement(wordList) || "undefined";
+    // If result of filtered word list is undefined, return an element
+    // from the unfiltered list.
+    return (
+      faker.random.arrayElement(wordList) ||
+      faker.random.arrayElement(faker.definitions.word.adverb)
+    );
   };
   /**
-   * returns a conjunction
+   * Returns a conjunction of random or optionally specified length.
+   * If specified length is unresolvable, returns random conjunction.
    *
-   * @method faker.conjunction
-   * @param {number} [length] - optional length of word to return. Returns
-   *                            stringified 'undefined' if unable to meet criteria.
+   * @method faker.word.conjunction
+   * @param {number} [length] - optional length of word to return
+   * @returns {string}          random conjunction
    */
   self.conjunction = function (length) {
     var wordList = faker.definitions.word.conjunction;
@@ -53,14 +65,20 @@ var Word = function (faker) {
         return word.length == length;
       });
     }
-    return faker.random.arrayElement(wordList) || "undefined";
+    // If result of filtered word list is undefined, return an element
+    // from the unfiltered list.
+    return (
+      faker.random.arrayElement(wordList) ||
+      faker.random.arrayElement(faker.definitions.word.conjunction)
+    );
   };
   /**
-   * returns an interjection
+   * Returns an interjection of random or optionally specified length.
+   * If specified length is unresolvable, returns random interjection.
    *
-   * @method faker.interjection
-   * @param {number} [length] - optional length of word to return. Returns
-   *                            stringified 'undefined' if unable to meet criteria.
+   * @method faker.word.interjection
+   * @param {number} [length] - optional length of word to return
+   * @returns {string}          random interjection
    */
   self.interjection = function (length) {
     var wordList = faker.definitions.word.interjection;
@@ -70,14 +88,20 @@ var Word = function (faker) {
         return word.length == length;
       });
     }
-    return faker.random.arrayElement(wordList) || "undefined";
+    // If result of filtered word list is undefined, return an element
+    // from the unfiltered list.
+    return (
+      faker.random.arrayElement(wordList) ||
+      faker.random.arrayElement(faker.definitions.word.interjection)
+    );
   };
   /**
-   * returns a noun
+   * Returns a noun of random or optionally specified length.
+   * If specified length is unresolvable, returns random noun.
    *
-   * @method faker.noun
-   * @param {number} [length] - optional length of word to return. Returns
-   *                            stringified 'undefined' if unable to meet criteria.
+   * @method faker.word.noun
+   * @param {number} [length] - optional length of word to return
+   * @returns {string}          random noun
    */
   self.noun = function (length) {
     var wordList = faker.definitions.word.noun;
@@ -87,14 +111,20 @@ var Word = function (faker) {
         return word.length == length;
       });
     }
-    return faker.random.arrayElement(wordList) || "undefined";
+    // If result of filtered word list is undefined, return an element
+    // from the unfiltered list.
+    return (
+      faker.random.arrayElement(wordList) ||
+      faker.random.arrayElement(faker.definitions.word.noun)
+    );
   };
   /**
-   * returns a preposition
+   * Returns a preposition of random or optionally specified length.
+   * If specified length is unresolvable, returns random preposition.
    *
-   * @method faker.preposition
-   * @param {number} [length] - optional length of word to return. Returns
-   *                            stringified 'undefined' if unable to meet criteria.
+   * @method faker.word.preposition
+   * @param {number} [length] - optional length of word to return
+   * @returns {string}          random preposition
    */
   self.preposition = function (length) {
     var wordList = faker.definitions.word.preposition;
@@ -104,14 +134,20 @@ var Word = function (faker) {
         return word.length == length;
       });
     }
-    return faker.random.arrayElement(wordList) || "undefined";
+    // If result of filtered word list is undefined, return an element
+    // from the unfiltered list.
+    return (
+      faker.random.arrayElement(wordList) ||
+      faker.random.arrayElement(faker.definitions.word.preposition)
+    );
   };
   /**
-   * returns a verb
+   * Returns a verb of random or optionally specified length.
+   * If specified length is unresolvable, returns random verb.
    *
-   * @method faker.verb
-   * @param {number} [length] - optional length of word to return. Returns
-   *                            stringified 'undefined' if unable to meet criteria.
+   * @method faker.word.verb
+   * @param {number} [length] - optional length of word to return
+   * @returns {string}          random verb
    */
   self.verb = function (length) {
     var wordList = faker.definitions.word.verb;
@@ -121,7 +157,12 @@ var Word = function (faker) {
         return word.length == length;
       });
     }
-    return faker.random.arrayElement(wordList) || "undefined";
+    // If result of filtered word list is undefined, return an element
+    // from the unfiltered list.
+    return (
+      faker.random.arrayElement(wordList) ||
+      faker.random.arrayElement(faker.definitions.word.verb)
+    );
   };
 
   return self;