docs: improve helpers jsdocs (#442)

1 files changed, 143 insertions, 57 deletions

diff --git a/src/helpers.ts b/src/helpers.ts
index e8191bfe..2b1be94b 100644
--- a/src/helpers.ts
+++ b/src/helpers.ts
@@ -1,5 +1,8 @@
 import type { Faker } from '.';
 
+/**
+ * A full card with various details.
+ */
 export interface Card {
   name: string;
   username: string;
@@ -41,6 +44,9 @@ export interface Card {
   }>;
 }
 
+/**
+ * A persons card with various details attempting to use a consistent context.
+ */
 export interface ContextualCard {
   name: string;
   username: string;
@@ -66,6 +72,9 @@ export interface ContextualCard {
   };
 }
 
+/**
+ * A user card with various details.
+ */
 export interface UserCard {
   name: string;
   username: string;
@@ -89,6 +98,9 @@ export interface UserCard {
   };
 }
 
+/**
+ * A transaction info.
+ */
 export interface Transaction {
   amount: string;
   date: Date;
@@ -110,11 +122,17 @@ export class Helpers {
   }
 
   /**
-   * backward-compatibility
+   * Backward-compatibility. Use `faker.random.arrayElement()` instead.
    *
-   * @method faker.helpers.randomize
-   * @param array
+   * Takes an array and returns a random element of the array.
+   *
+   * @param array The array to select an element from.
+   *
+   * @example
+   * faker.helpers.randomize() // 'c'
+   * faker.helpers.randomize([1, 2, 3]) // '2'
    */
+  // TODO ST-DDT 2022-02-06: Mark as deprecated
   randomize<T = string>(
     array: ReadonlyArray<T> = ['a', 'b', 'c'] as unknown as ReadonlyArray<T>
   ): T {
@@ -122,10 +140,15 @@ export class Helpers {
   }
 
   /**
-   * slugifies string
+   * Slugifies the given string.
+   * For that all spaces (` `) are replaced by hyphens (`-`)
+   * and most non word characters except for dots and hyphens will be removed.
    *
-   * @method faker.helpers.slugify
-   * @param string
+   * @param string The input to slugify.
+   *
+   * @example
+   * faker.helpers.slugify() // ''
+   * faker.helpers.slugify("Hello world!") // 'Hello-world'
    */
   slugify(string: string = ''): string {
     return string
@@ -134,11 +157,17 @@ export class Helpers {
   }
 
   /**
-   * Parses string for a symbol and replace it with a random number from 1-10
+   * Parses the given string symbol by symbol and replaces the placeholders with digits (`0` - `9`).
+   * `!` will be replaced by digits >=2 (`2` - `9`).
+   *
+   * @param string The template string to parse.
+   * @param symbol The symbol to replace with digits. Defaults to `'#'`.
    *
-   * @method faker.helpers.replaceSymbolWithNumber
-   * @param string
-   * @param symbol defaults to `"#"`
+   * @example
+   * faker.helpers.replaceSymbolWithNumber() // ''
+   * faker.helpers.replaceSymbolWithNumber('#####') // '04812'
+   * faker.helpers.replaceSymbolWithNumber('!####') // '27378'
+   * faker.helpers.replaceSymbolWithNumber('Your pin is: !####') // '29841'
    */
   replaceSymbolWithNumber(string: string = '', symbol: string = '#'): string {
     let str = '';
@@ -155,11 +184,20 @@ export class Helpers {
   }
 
   /**
-   * Parses string for symbols (numbers or letters) and replaces them appropriately (# will be replaced with number,
-   * ? with letter and * will be replaced with number or letter)
+   * Parses the given string symbol by symbols and replaces the placeholder appropriately.
    *
-   * @method faker.helpers.replaceSymbols
-   * @param string
+   * - `#` will be replaced with a digit (`0` - `9`).
+   * - `?` will be replaced with an upper letter ('A' - 'Z')
+   * - and `*` will be replaced with either a digit or letter.
+   *
+   * @param string The template string to parse.
+   *
+   * @example
+   * faker.helpers.replaceSymbols() // ''
+   * faker.helpers.replaceSymbols('#####') // '98441'
+   * faker.helpers.replaceSymbols('?????') // 'ZYRQQ'
+   * faker.helpers.replaceSymbols('*****') // '4Z3P7'
+   * faker.helpers.replaceSymbols('Your pin is: #?*#?*') // '0T85L1'
    */
   replaceSymbols(string: string = ''): string {
     const alpha = [
@@ -209,11 +247,17 @@ export class Helpers {
   }
 
   /**
-   * replace symbols in a credit card schems including Luhn checksum
+   * Replaces the symbols and patterns in a credit card schema including Luhn checksum.
+   *
+   * This method supports both range patterns `[4-9]` as well as the patterns used by `replaceSymbolWithNumber()`.
+   * `L` will be replaced with the appropriate Luhn checksum.
+   *
+   * @param string The credit card format pattern. Defaults to `6453-####-####-####-###L`.
+   * @param symbol The symbol to replace with a digit.
    *
-   * @method faker.helpers.replaceCreditCardSymbols
-   * @param string
-   * @param symbol
+   * @example
+   * faker.helpers.replaceCreditCardSymbols() // '6453-4876-8626-8995-3779'
+   * faker.helpers.replaceCreditCardSymbols('1234-[4-9]-##!!-L') // '1234-9-5298-2'
    */
 
   replaceCreditCardSymbols(
@@ -252,11 +296,15 @@ export class Helpers {
   }
 
   /**
-   * String repeat helper, alternative to String.prototype.repeat.... See PR #382
+   * Repeats the given string the given number of times.
    *
-   * @method faker.helpers.repeatString
-   * @param string
-   * @param num
+   * @param string The string to repeat.
+   * @param num The number of times to repeat it. Defaults to `0`.
+   *
+   * @example
+   * faker.helpers.repeatString('Hello world! ') // ''
+   * faker.helpers.repeatString('Hello world! ', 1) // 'Hello world! '
+   * faker.helpers.repeatString('Hello world! ', 2) // 'Hello world! Hello world! '
    */
   repeatString(string: string, num = 0): string {
     let text = '';
@@ -267,12 +315,21 @@ export class Helpers {
   }
 
   /**
-   * parse string patterns in a similar way to RegExp
+   * Replaces the regex like expressions in the given string with matching values.
+   *
+   * Supported patterns:
+   * - `.{times}` => Repeat the character exactly `times` times.
+   * - `.{min,max}` => Repeat the character `min` to `max` times.
+   * - `[min-max]` => Generate a number between min and max (inclusive).
    *
-   * e.g. "#{3}test[1-5]" -> "###test4"
+   * @param string The template string to to parse.
    *
-   * @method faker.helpers.regexpStyleStringParse
-   * @param string
+   * @example
+   * faker.helpers.regexpStyleStringParse() // ''
+   * faker.helpers.regexpStyleStringParse('#{5}') // '#####'
+   * faker.helpers.regexpStyleStringParse('#{2,9}') // '#######'
+   * faker.helpers.regexpStyleStringParse('[500-15000]') // '8375'
+   * faker.helpers.regexpStyleStringParse('#{3}test[1-5]') // '###test3'
    */
   regexpStyleStringParse(string: string = ''): string {
     // Deal with range repeat `{min,max}`
@@ -330,18 +387,22 @@ export class Helpers {
   }
 
   /**
-   * Takes an array and randomizes it in place then returns it
+   * Takes an array and randomizes it in place then returns it.
    *
-   * Uses the modern version of the Fisher–Yates algorithm
+   * Uses the modern version of the Fisher–Yates algorithm.
    *
-   * @method faker.helpers.shuffle
-   * @param o
+   * @param o The array to shuffle. Defaults to `[]`.
+   *
+   * @example
+   * faker.helpers.shuffle() // []
+   * faker.helpers.shuffle(['a', 'b', 'c']) // [ 'b', 'c', 'a' ]
    */
   shuffle<T>(o?: T[]): T[] {
     if (typeof o === 'undefined' || o.length === 0) {
       return o || [];
     }
 
+    // TODO ST-DDT 2022-02-06: This default will never be taken!?
     o = o || (['a', 'b', 'c'] as unknown as T[]);
     for (let x: T, j: number, i = o.length - 1; i > 0; --i) {
       j = this.faker.datatype.number(i);
@@ -354,15 +415,15 @@ export class Helpers {
 
   /**
    * Takes an array of strings or function that returns a string
-   * and outputs a unique array of strings based on that source
+   * and outputs a unique array of strings based on that source.
+   * This method does not store the unique state between invocations.
+   *
+   * @param source The strings to choose from or a function that generates a string.
+   * @param length The number of elements to generate.
    *
    * @example uniqueArray(faker.random.word, 50)
    * @example uniqueArray(faker.definitions.name.first_name, 6)
    * @example uniqueArray(["Hello", "World", "Goodbye"], 2)
-   *
-   * @method faker.helpers.uniqueArray
-   * @param source
-   * @param length
    */
   uniqueArray<T>(source: T[] | (() => T), length: number): T[] {
     if (Array.isArray(source)) {
@@ -385,11 +446,14 @@ export class Helpers {
   }
 
   /**
-   * mustache
+   * Replaces the `{{placeholder}}` patterns in the given string mustache style.
+   *
+   * @param str The template string to parse.
+   * @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
-   * @param str
-   * @param data
    */
   mustache(
     str: string | undefined,
@@ -413,13 +477,18 @@ export class Helpers {
     return str;
   }
 
-  // TODO @Shinigami92 2022-01-11: We might have a bug with the `phone` definition
-  // I may be `phone_number` instead
-
   /**
-   * createCard
+   * Generates a full card with various random details.
    *
-   * @method faker.helpers.createCard
+   * @example
+   * faker.helpers.createCard()
+   * // {
+   * //   name: 'Maxine Abbott',
+   * //   username: 'Idell_Kautzer60',
+   * //   email: '[email protected]',
+   * //   address: {
+   * //     streetA: 'Drake Avenue',
+   * // ...
    */
   createCard(): Card {
     return {
@@ -476,9 +545,17 @@ export class Helpers {
   }
 
   /**
-   * contextualCard
+   * Generates a persons card with various details attempting to use a consistent context.
    *
-   * @method faker.helpers.contextualCard
+   * @example
+   * faker.helpers.contextualCard()
+   * // {
+   * //   name: 'Eveline',
+   * //   username: 'Eveline.Brekke56',
+   * //   avatar: 'https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/122.jpg',
+   * //   email: '[email protected]',
+   * //   dob: 1964-05-06T05:14:37.874Z,
+   * // ...
    */
   contextualCard(): ContextualCard {
     const name = this.faker.name.firstName();
@@ -515,9 +592,17 @@ export class Helpers {
   }
 
   /**
-   * userCard
+   * Generates a user card with various details.
    *
-   * @method faker.helpers.userCard
+   * @example
+   * faker.helpers.userCard()
+   * // {
+   * //   name: 'Jodi Ferry',
+   * //   username: 'Maybell.Kris',
+   * //   email: '[email protected]',
+   * //   address: {
+   * //     street: 'McKenzie Estates',
+   * // ....
    */
   userCard(): UserCard {
     return {
@@ -545,9 +630,18 @@ export class Helpers {
   }
 
   /**
-   * createTransaction
+   * Generates an example transaction.
    *
-   * @method faker.helpers.createTransaction
+   * @example
+   * faker.helpers.createTransaction()
+   * // {
+   * //   amount: '551.32',
+   * //   date: 2012-02-01T23:00:00.000Z,
+   * //   business: 'Will, Fisher and Marks',
+   * //   name: 'Investment Account (...8755)',
+   * //   type: 'invoice',
+   * //   account: '41796240'
+   * // }
    */
   createTransaction(): Transaction {
     return {
@@ -562,11 +656,3 @@ export class Helpers {
     };
   }
 }
-
-/*
-String.prototype.capitalize = function () { //v1.0
-    return this.replace(/\w+/g, function (a) {
-        return a.charAt(0).toUpperCase() + a.substr(1).toLowerCase();
-    });
-};
-*/