chore: enable jsdoc/sort-tags (#512)

13 files changed, 57 insertions, 97 deletions

diff --git a/.eslintrc.js b/.eslintrc.js
index 02c20fcb..55254d7a 100644
--- a/.eslintrc.js
+++ b/.eslintrc.js
@@ -62,9 +62,8 @@ module.exports = defineConfig({
         'jsdoc/require-returns': 'off',
         'jsdoc/tag-lines': 'off',
 
-        // Rule will come in one of the next releases: https://github.com/gajus/eslint-plugin-jsdoc/pull/833
         // We want to explicitly set this rule to error in the future
-        // 'jsdoc/sort-tags': 'warn',
+        'jsdoc/sort-tags': 'warn',
       },
       settings: {
         jsdoc: {
diff --git a/src/address.ts b/src/address.ts
index 7dde0bca..eff72f2f 100644
--- a/src/address.ts
+++ b/src/address.ts
@@ -30,12 +30,12 @@ export class Address {
    * @param format The optional format used to generate the the zip code.
    * By default, a random format is used from the locale zip formats.
    *
+   * @see faker.helpers.replaceSymbols()
+   *
    * @example
    * faker.address.zipCode() // '17839'
    * faker.address.zipCode('####') // '6925'
    *
-   * @see
-   * faker.helpers.replaceSymbols()
    */
   zipCode(format?: string): string {
     // if zip format is not specified, use the zip format defined for the locale
diff --git a/src/company.ts b/src/company.ts
index adc7345b..e0d4721f 100644
--- a/src/company.ts
+++ b/src/company.ts
@@ -32,6 +32,7 @@ export class Company {
 
   /**
    * Generates a random company name.
+   *
    * @param format The optional format index used to select a format.
    *
    * @example
diff --git a/src/date.ts b/src/date.ts
index 95d5e487..97b54b73 100644
--- a/src/date.ts
+++ b/src/date.ts
@@ -20,12 +20,12 @@ export class _Date {
    * @param years The range of years the date may be in the past. Defaults to `1`.
    * @param refDate The date to use as reference point for the newly generated date. Defaults to now.
    *
+   * @see faker.date.recent()
+   *
    * @example
    * faker.date.past() // '2021-12-03T05:40:44.408Z'
    * faker.date.past(10) // '2017-10-25T21:34:19.488Z'
    * faker.date.past(10, '2020-01-01T00:00:00.000Z') // '2017-08-18T02:59:12.350Z'
-   *
-   * @see faker.date.recent()
    */
   past(years?: number, refDate?: string): Date {
     let date = new Date();
@@ -51,12 +51,12 @@ export class _Date {
    * @param years The range of years the date may be in the future. Defaults to `1`.
    * @param refDate The date to use as reference point for the newly generated date. Defaults to now.
    *
+   * @see faker.date.soon()
+   *
    * @example
    * faker.date.future() // '2022-11-19T05:52:49.100Z'
    * faker.date.future(10) // '2030-11-23T09:38:28.710Z'
    * faker.date.future(10, '2020-01-01T00:00:00.000Z') // '2020-12-13T22:45:10.252Z'
-   *
-   * @see faker.date.soon()
    */
   future(years?: number, refDate?: string): Date {
     let date = new Date();
@@ -135,12 +135,12 @@ export class _Date {
    * @param days The range of days the date may be in the past. Defaults to `1`.
    * @param refDate The date to use as reference point for the newly generated date. Defaults to now.
    *
+   * @see faker.date.past()
+   *
    * @example
    * faker.date.recent() // '2022-02-04T02:09:35.077Z'
    * faker.date.recent(10) // '2022-01-29T06:12:12.829Z'
    * faker.date.recent(10, '2020-01-01T00:00:00.000Z') // '2019-12-27T18:11:19.117Z'
-   *
-   * @see faker.date.past()
    */
   recent(days?: number, refDate?: string): Date {
     let date = new Date();
@@ -166,12 +166,12 @@ export class _Date {
    * @param days The range of days the date may be in the future. Defaults to `1`.
    * @param refDate The date to use as reference point for the newly generated date. Defaults to now.
    *
+   * @see faker.date.future()
+   *
    * @example
    * faker.date.soon() // '2022-02-05T09:55:39.216Z'
    * faker.date.soon(10) // '2022-02-11T05:14:39.138Z'
    * faker.date.soon(10, '2020-01-01T00:00:00.000Z') // '2020-01-01T02:40:44.990Z'
-   *
-   * @see faker.date.future()
    */
   soon(days?: number, refDate?: string): Date {
     let date = new Date();
diff --git a/src/finance.ts b/src/finance.ts
index ece9f7ec..35fd9d87 100644
--- a/src/finance.ts
+++ b/src/finance.ts
@@ -77,7 +77,7 @@ export class Finance {
 
   /**
    * Generates a random masked number.
-
+   *
    * @param length The length of the unmasked number. Defaults to `4`.
    * @param parens Whether to use surrounding parenthesis. Defaults to `true`.
    * @param ellipsis Whether to prefix the numbers with an ellipsis. Defaults to `true`.
diff --git a/src/git.ts b/src/git.ts
index d708bc12..b77b79cb 100644
--- a/src/git.ts
+++ b/src/git.ts
@@ -48,6 +48,9 @@ export class Git {
   /**
    * Generates a random commit entry.
    *
+   * @param options Options for the commit entry.
+   * @param options.merge Set to `true` to generate a merge message line.
+   *
    * @example
    * faker.git.commitEntry()
    * // commit fe8c38a965d13d9794eb36918cb24cebe49a45c2
diff --git a/src/helpers.ts b/src/helpers.ts
index 385d4f3e..0bb6b4d0 100644
--- a/src/helpers.ts
+++ b/src/helpers.ts
@@ -452,8 +452,6 @@ export class Helpers {
    * @param data The data used to populate the placeholders.
    * This is a record where the key is the template placeholder,
    * whereas the value is either a string or a function suitable for `String.replace()`.
-   *
-   * @method faker.helpers.mustache
    */
   mustache(
     str: string | undefined,
diff --git a/src/image_providers/lorempicsum.ts b/src/image_providers/lorempicsum.ts
index a3136458..56553af0 100644
--- a/src/image_providers/lorempicsum.ts
+++ b/src/image_providers/lorempicsum.ts
@@ -4,14 +4,12 @@ export class LoremPicsum {
   constructor(private readonly faker: Faker) {}
 
   /**
-   * image
+   * Search image from unsplash
    *
    * @param width
    * @param height
    * @param grayscale
    * @param blur 1-10
-   * @method faker.image.lorempicsum.image
-   * @description search image from unsplash
    */
   image(
     width?: number,
@@ -23,26 +21,22 @@ export class LoremPicsum {
   }
 
   /**
-   * imageGrayscaled
+   * Search grayscale image from unsplash
    *
    * @param width
    * @param height
    * @param grayscale
-   * @method faker.image.lorempicsum.imageGrayscaled
-   * @description search grayscale image from unsplash
    */
   imageGrayscale(width?: number, height?: number, grayscale?: boolean): string {
     return this.imageUrl(width, height, grayscale);
   }
 
   /**
-   * imageBlurred
+   * Search blurred image from unsplash
    *
    * @param width
    * @param height
    * @param blur 1-10
-   * @method faker.image.lorempicsum.imageBlurred
-   * @description search blurred image from unsplash
    */
   imageBlurred(
     width?: number,
@@ -53,15 +47,13 @@ export class LoremPicsum {
   }
 
   /**
-   * imageRandomSeeded
+   * Search same random image from unsplash, based on a seed
    *
    * @param width
    * @param height
    * @param grayscale
    * @param blur 1-10
    * @param seed
-   * @method faker.image.lorempicsum.imageRandomSeeded
-   * @description search same random image from unsplash, based on a seed
    */
   imageRandomSeeded(
     width?: number,
@@ -75,8 +67,6 @@ export class LoremPicsum {
 
   /**
    * avatar
-   *
-   * @method faker.image.lorempicsum.avatar
    */
   avatar(): string {
     return this.faker.internet.avatar();
@@ -90,7 +80,6 @@ export class LoremPicsum {
    * @param grayscale
    * @param blur 1-10
    * @param seed
-   * @method faker.image.lorempicsum.imageUrl
    */
   imageUrl(
     width?: number,
diff --git a/src/image_providers/lorempixel.ts b/src/image_providers/lorempixel.ts
index b6717b46..2b7d5263 100644
--- a/src/image_providers/lorempixel.ts
+++ b/src/image_providers/lorempixel.ts
@@ -9,7 +9,6 @@ export class Lorempixel {
    * @param width
    * @param height
    * @param randomize
-   * @method faker.image.lorempixel.image
    */
   image(width?: number, height?: number, randomize?: boolean): string {
     const categories = [
@@ -36,8 +35,6 @@ export class Lorempixel {
 
   /**
    * avatar
-   *
-   * @method faker.image.lorempixel.avatar
    */
   avatar(): string {
     return this.faker.internet.avatar();
@@ -50,7 +47,6 @@ export class Lorempixel {
    * @param height
    * @param category
    * @param randomize
-   * @method faker.image.lorempixel.imageUrl
    */
   imageUrl(
     width?: number,
@@ -79,7 +75,6 @@ export class Lorempixel {
    * @param width
    * @param height
    * @param randomize
-   * @method faker.image.lorempixel.abstract
    */
   abstract(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -96,7 +91,6 @@ export class Lorempixel {
    * @param width
    * @param height
    * @param randomize
-   * @method faker.image.lorempixel.animals
    */
   animals(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -113,7 +107,6 @@ export class Lorempixel {
    * @param width
    * @param height
    * @param randomize
-   * @method faker.image.lorempixel.business
    */
   business(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -130,7 +123,6 @@ export class Lorempixel {
    * @param width
    * @param height
    * @param randomize
-   * @method faker.image.lorempixel.cats
    */
   cats(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -147,7 +139,6 @@ export class Lorempixel {
    * @param width
    * @param height
    * @param randomize
-   * @method faker.image.lorempixel.city
    */
   city(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -164,7 +155,6 @@ export class Lorempixel {
    * @param width
    * @param height
    * @param randomize
-   * @method faker.image.lorempixel.food
    */
   food(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -181,7 +171,6 @@ export class Lorempixel {
    * @param width
    * @param height
    * @param randomize
-   * @method faker.image.lorempixel.nightlife
    */
   nightlife(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -198,7 +187,6 @@ export class Lorempixel {
    * @param width
    * @param height
    * @param randomize
-   * @method faker.image.lorempixel.fashion
    */
   fashion(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -215,7 +203,6 @@ export class Lorempixel {
    * @param width
    * @param height
    * @param randomize
-   * @method faker.image.lorempixel.people
    */
   people(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -232,7 +219,6 @@ export class Lorempixel {
    * @param width
    * @param height
    * @param randomize
-   * @method faker.image.lorempixel.nature
    */
   nature(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -249,7 +235,6 @@ export class Lorempixel {
    * @param width
    * @param height
    * @param randomize
-   * @method faker.image.lorempixel.sports
    */
   sports(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -266,7 +251,6 @@ export class Lorempixel {
    * @param width
    * @param height
    * @param randomize
-   * @method faker.image.lorempixel.technics
    */
   technics(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -283,7 +267,6 @@ export class Lorempixel {
    * @param width
    * @param height
    * @param randomize
-   * @method faker.image.lorempixel.transport
    */
   transport(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
diff --git a/src/image_providers/unsplash.ts b/src/image_providers/unsplash.ts
index 16bf4f11..45fbdd6c 100644
--- a/src/image_providers/unsplash.ts
+++ b/src/image_providers/unsplash.ts
@@ -13,13 +13,11 @@ export class Unsplash {
   constructor(private readonly faker: Faker) {}
 
   /**
-   * image
+   * Search image from unsplash
    *
    * @param width
    * @param height
    * @param keyword
-   * @method faker.image.unsplash.image
-   * @description search image from unsplash
    */
   image(width?: number, height?: number, keyword?: string): string {
     return this.imageUrl(width, height, undefined, keyword);
@@ -27,8 +25,6 @@ export class Unsplash {
 
   /**
    * avatar
-   *
-   * @method faker.image.unsplash.avatar
    */
   avatar(): string {
     return this.faker.internet.avatar();
@@ -41,7 +37,6 @@ export class Unsplash {
    * @param height
    * @param category
    * @param keyword
-   * @method faker.image.unsplash.imageUrl
    */
   imageUrl(
     width?: number,
@@ -78,7 +73,6 @@ export class Unsplash {
    * @param width
    * @param height
    * @param keyword
-   * @method faker.image.unsplash.food
    */
   food(width?: number, height?: number, keyword?: string): string {
     return this.faker.image.unsplash.imageUrl(width, height, 'food', keyword);
@@ -90,7 +84,6 @@ export class Unsplash {
    * @param width
    * @param height
    * @param keyword
-   * @method faker.image.unsplash.people
    */
   people(width?: number, height?: number, keyword?: string): string {
     return this.faker.image.unsplash.imageUrl(width, height, 'people', keyword);
@@ -102,7 +95,6 @@ export class Unsplash {
    * @param width
    * @param height
    * @param keyword
-   * @method faker.image.unsplash.nature
    */
   nature(width?: number, height?: number, keyword?: string): string {
     return this.faker.image.unsplash.imageUrl(width, height, 'nature', keyword);
@@ -114,7 +106,6 @@ export class Unsplash {
    * @param width
    * @param height
    * @param keyword
-   * @method faker.image.unsplash.technology
    */
   technology(width?: number, height?: number, keyword?: string): string {
     return this.faker.image.unsplash.imageUrl(
@@ -131,7 +122,6 @@ export class Unsplash {
    * @param width
    * @param height
    * @param keyword
-   * @method faker.image.unsplash.objects
    */
   objects(width?: number, height?: number, keyword?: string): string {
     return this.faker.image.unsplash.imageUrl(
@@ -148,7 +138,6 @@ export class Unsplash {
    * @param width
    * @param height
    * @param keyword
-   * @method faker.image.unsplash.buildings
    */
   buildings(width?: number, height?: number, keyword?: string): string {
     return this.faker.image.unsplash.imageUrl(
diff --git a/src/name.ts b/src/name.ts
index e62ba45e..663ae748 100644
--- a/src/name.ts
+++ b/src/name.ts
@@ -17,15 +17,15 @@ export class Name {
   /**
    * Returns a random first name.
    *
+   * @param gender The optional gender to use.
+   * Can be either `'male'` (or `0`) or `'female'` (or `1`).
+   *
    * @example
    * faker.name.firstName() // 'Antwan'
    * faker.name.firstName("female") // 'Victoria'
    * faker.name.firstName(1) // 'Ashley'
    * faker.name.firstName("male") // 'Tom'
    * faker.name.firstName(0) // 'Ismael'
-   *
-   * @param gender The optional gender to use.
-   * Can be either `'male'` (or `0`) or `'female'` (or `1`).
    */
   firstName(gender?: string | number): string {
     if (
@@ -72,15 +72,15 @@ export class Name {
   /**
    * Returns a random last name.
    *
+   * @param gender The optional gender to use.
+   * Can be either `'male'` (or `0`) or `'female'` (or `1`).
+   *
    * @example
    * faker.name.lastName() // 'Hauck'
    * faker.name.lastName("female") // 'Grady'
    * faker.name.lastName(1) // 'Kshlerin'
    * faker.name.lastName("male") // 'Barton'
    * faker.name.lastName(0) // 'Lockman'
-   *
-   * @param gender The optional gender to use.
-   * Can be either `'male'` (or `0`) or `'female'` (or `1`).
    */
   lastName(gender?: string | number): string {
     if (
@@ -111,15 +111,15 @@ export class Name {
   /**
    * Returns a random middle name.
    *
+   * @param gender The optional gender to use.
+   * Can be either `'male'` (or `0`) or `'female'` (or `1`).
+   *
    * @example
    * faker.name.middleName() // 'Доброславівна'
    * faker.name.middleName("female") // 'Анастасівна'
    * faker.name.middleName(1) // 'Анатоліївна'
    * faker.name.middleName("male") // 'Вікторович'
    * faker.name.middleName(0) // 'Стефанович'
-   *
-   * @param gender The optional gender to use.
-   * Can be either `'male'` (or `0`) or `'female'` (or `1`).
    */
   middleName(gender?: string | number): string {
     if (
@@ -148,17 +148,17 @@ export class Name {
   /**
    * Generates a random full name.
    *
+   * @param firstName The optional first name to use. If not specified a random one will be chosen.
+   * @param lastName The optional last name to use. If not specified a random one will be chosen.
+   * @param gender The optional gender to use.
+   * Can be either `'male'` (or `0`) or `'female'` (or `1`).
+   *
    * @example
    * faker.name.findName() // 'Allen Brown'
    * faker.name.findName('Joann') // 'Joann Osinski'
    * faker.name.findName('Marcella', '', 1) // 'Mrs. Marcella Huels'
    * faker.name.findName(undefined, 'Beer') // 'Mr. Alfonso Beer'
    * faker.name.findName(undefined, undefined, 0) // 'Fernando Schaefer'
-   *
-   * @param firstName The optional first name to use. If not specified a random one will be chosen.
-   * @param lastName The optional last name to use. If not specified a random one will be chosen.
-   * @param gender The optional gender to use.
-   * Can be either `'male'` (or `0`) or `'female'` (or `1`).
    */
   findName(
     firstName?: string,
@@ -216,11 +216,11 @@ export class Name {
   /**
    * Return a random gender.
    *
+   * @param binary Whether to return only binary gender names. Defaults to false.
+   *
    * @example
    * faker.name.gender() // 'Trans*Man'
    * faker.name.gender(true) // 'Female'
-   *
-   * @param binary Whether to return only binary gender names. Defaults to false.
    */
   gender(binary?: boolean): string {
     if (binary) {
@@ -235,15 +235,15 @@ export class Name {
   /**
    * Returns a random name prefix.
    *
+   * @param gender The optional gender to use.
+   * Can be either `'male'` (or `0`) or `'female'` (or `1`).
+   *
    * @example
    * faker.name.prefix() // 'Miss'
    * faker.name.prefix('female') // 'Ms.'
    * faker.name.prefix(1) // 'Dr.'
    * faker.name.prefix('male') // 'Mr.'
    * faker.name.prefix(0) // 'Mr.'
-   *
-   * @param gender The optional gender to use.
-   * Can be either `'male'` (or `0`) or `'female'` (or `1`).
    */
   prefix(gender?: string | number): string {
     if (
diff --git a/src/random.ts b/src/random.ts
index 50fd4dba..28abb3c2 100644
--- a/src/random.ts
+++ b/src/random.ts
@@ -5,7 +5,7 @@ import type { Faker } from '.';
  *
  * @param arr existing array of characters
  * @param values array of characters which should be removed
- * @return new array without banned characters
+ * @returns new array without banned characters
  */
 function arrayRemove<T>(arr: T[], values: T[]): T[] {
   values.forEach((value) => {
@@ -44,6 +44,8 @@ export class Random {
    * @param options.max Upper bound for generated number. Defaults to `99999`.
    * @param options.precision Precision of the generated number. Defaults to `1`.
    *
+   * @see faker.datatype.number()
+   *
    * @example
    * faker.random.number() // 55422
    * faker.random.number(100) // 52
@@ -53,7 +55,6 @@ export class Random {
    * faker.random.number({ min: 10, max: 100, precision: 0.01 }) // 36.94
    *
    * @deprecated
-   * @see faker.datatype.number()
    */
   number(
     options?: number | { min?: number; max?: number; precision?: number }
@@ -72,6 +73,8 @@ export class Random {
    * @param options.max Upper bound for generated number. Defaults to `99999`.
    * @param options.precision Precision of the generated number. Defaults to `0.01`.
    *
+   * @see faker.datatype.float()
+   *
    * @example
    * faker.random.float() // 51696.36
    * faker.random.float(0.1) // 52023.2
@@ -81,7 +84,6 @@ export class Random {
    * faker.random.float({ min: 10, max: 100, precision: 0.001 }) // 57.315
    *
    * @deprecated
-   * @see faker.datatype.float()
    */
   float(
     options?: number | { min?: number; max?: number; precision?: number }
@@ -154,7 +156,6 @@ export class Random {
   /**
    * Returns a random key or value from given object.
    *
-   * @method faker.random.objectElement
    * @param object
    * @param field
    */
@@ -179,11 +180,12 @@ export class Random {
   /**
    * Returns a UUID v4 ([Universally Unique Identifier](https://en.wikipedia.org/wiki/Universally_unique_identifier)).
    *
+   * @see faker.datatype.uuid()
+   *
    * @example
    * faker.random.uuid() // '4136cd0b-d90b-4af7-b485-5d1ded8db252'
    *
    * @deprecated
-   * @see faker.datatype.uuid()
    */
   uuid(): string {
     console.warn(
@@ -195,11 +197,12 @@ export class Random {
   /**
    * Returns the boolean value true or false.
    *
+   * @see faker.datatype.boolean()
+   *
    * @example
    * faker.random.boolean() // false
    *
    * @deprecated
-   * @see faker.datatype.boolean()
    */
   boolean(): boolean {
     console.warn(
@@ -282,7 +285,6 @@ export class Random {
   /**
    * locale
    *
-   * @method faker.random.image
    * @deprecated
    */
   image(): string {
@@ -294,8 +296,6 @@ export class Random {
 
   /**
    * locale
-   *
-   * @method faker.random.locale
    */
   locale(): string {
     return this.faker.random.arrayElement(Object.keys(this.faker.locales));
@@ -304,7 +304,6 @@ export class Random {
   /**
    * alpha. returns lower/upper alpha characters based count and upcase options
    *
-   * @method faker.random.alpha
    * @param options // defaults to { count: 1, upcase: false, bannedChars: [] }
    */
   // TODO @Shinigami92 2022-02-14: Tests covered `(count, options)`, but they were never typed like that
@@ -375,7 +374,6 @@ export class Random {
   /**
    * alphaNumeric
    *
-   * @method faker.random.alphaNumeric
    * @param count defaults to 1
    * @param options // defaults to { bannedChars: [] }
    * @param options.bannedChars array of characters which should be banned in new string
@@ -442,8 +440,8 @@ export class Random {
   /**
    * hexaDecimal
    *
-   * @method faker.random.hexaDecimal
    * @param count defaults to 1
+   *
    * @deprecated
    */
   hexaDecimal(count?: number): string {
diff --git a/src/word.ts b/src/word.ts
index a5ee8241..b91c1356 100644
--- a/src/word.ts
+++ b/src/word.ts
@@ -15,7 +15,7 @@ export class Word {
    * Returns an adjective of random or optionally specified length.
    * If specified length is unresolvable, returns random adjective.
    *
-   * @param optional length of word to return
+   * @param length The optional length of word to return.
    */
   adjective(length?: number): string {
     let wordList = this.faker.definitions.word.adjective;
@@ -37,7 +37,7 @@ export class Word {
    * Returns an adverb of random or optionally specified length.
    * If specified length is unresolvable, returns random adverb.
    *
-   * @param optional length of word to return
+   * @param length The optional length of word to return.
    */
   adverb(length?: number): string {
     let wordList = this.faker.definitions.word.adverb;
@@ -59,7 +59,7 @@ export class Word {
    * Returns a conjunction of random or optionally specified length.
    * If specified length is unresolvable, returns random conjunction.
    *
-   * @param optional length of word to return
+   * @param length The optional length of word to return.
    */
   conjunction(length?: number): string {
     let wordList = this.faker.definitions.word.conjunction;
@@ -81,7 +81,7 @@ export class Word {
    * Returns an interjection of random or optionally specified length.
    * If specified length is unresolvable, returns random interjection.
    *
-   * @param optional length of word to return
+   * @param length The optional length of word to return.
    */
   interjection(length?: number): string {
     let wordList = this.faker.definitions.word.interjection;
@@ -103,7 +103,7 @@ export class Word {
    * Returns a noun of random or optionally specified length.
    * If specified length is unresolvable, returns random noun.
    *
-   * @param optional length of word to return
+   * @param length The optional length of word to return.
    */
   noun(length?: number): string {
     let wordList = this.faker.definitions.word.noun;
@@ -125,7 +125,7 @@ export class Word {
    * Returns a preposition of random or optionally specified length.
    * If specified length is unresolvable, returns random preposition.
    *
-   * @param optional length of word to return
+   * @param length The optional length of word to return.
    */
   preposition(length?: number): string {
     let wordList = this.faker.definitions.word.preposition;
@@ -147,7 +147,7 @@ export class Word {
    * Returns a verb of random or optionally specified length.
    * If specified length is unresolvable, returns random verb.
    *
-   * @param optional length of word to return
+   * @param length The optional length of word to return.
    */
   verb(length?: number): string {
     let wordList = this.faker.definitions.word.verb;