docs: various fixes (#523)

Author: ST-DDT

src/datatype.ts

@@ -1,5 +1,8 @@
 import type { Faker } from '.';
 
+/**
+ * Module to generate various primitive values and data types.
+ */
 export class Datatype {
   constructor(private readonly faker: Faker, seed?: any[] | any) {
     // Use a user provided seed if it is an array or number
@@ -139,7 +142,7 @@ export class Datatype {
   }
 
   /**
-   * Returns a string containing UTF-16 chars between 33 and 125 ('!' to '}').
+   * Returns a string containing UTF-16 chars between 33 and 125 (`!` to `}`).
    *
    * @param length Length of the generated string. Max length is `2^20`. Defaults to `10`.
    *

src/date.ts

@@ -99,7 +99,7 @@ export class _Date {
    *
    * @param from The early date boundary.
    * @param to The late date boundary.
-   * @param num The number of dates to generate. Defaults to 3.
+   * @param num The number of dates to generate. Defaults to `3`.
    *
    * @example
    * faker.date.betweens('2020-01-01T00:00:00.000Z', '2030-01-01T00:00:00.000Z')
@@ -195,8 +195,8 @@ export class _Date {
    * Returns a random name of a month.
    *
    * @param options The optional options to use.
-   * @param options.abbr Whether to return an abbreviation. Defaults to false.
-   * @param options.context Whether to return the name of a month in a context. Defaults to false.
+   * @param options.abbr Whether to return an abbreviation. Defaults to `false`.
+   * @param options.context Whether to return the name of a month in a context. Defaults to `false`.
    *
    * @example
    * faker.date.month() // 'October'
@@ -228,8 +228,8 @@ export class _Date {
    * Returns a random day of the week.
    *
    * @param options The optional options to use.
-   * @param options.abbr Whether to return an abbreviation. Defaults to false.
-   * @param options.context Whether to return the day of the week in a context. Defaults to false.
+   * @param options.abbr Whether to return an abbreviation. Defaults to `false`.
+   * @param options.context Whether to return the day of the week in a context. Defaults to `false`.
    *
    * @example
    * faker.date.weekday() // 'Monday'

src/finance.ts

@@ -24,7 +24,7 @@ export class Finance {
   /**
    * Generates a random account number.
    *
-   * @param length The length of the account number. Defaults to 8.
+   * @param length The length of the account number. Defaults to `8`.
    *
    * @example
    * faker.finance.account() // 92842238
@@ -113,9 +113,6 @@ export class Finance {
     return template;
   }
 
-  // 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
-
   /**
    * Generates a random amount between the given bounds (inclusive).
    *
@@ -256,7 +253,7 @@ export class Finance {
    *
    * @example
    * faker.finance.creditCardNumber() // '4427163488668'
-   * faker.finance.creditCardNumber('Visa') // '4882664999003'
+   * faker.finance.creditCardNumber('visa') // '4882664999003'
    * faker.finance.creditCardNumber('63[7-9]#-####-####-###L') // '6375-3265-4676-6644'
    */
   creditCardNumber(provider = ''): string {

src/helpers.ts

@@ -110,6 +110,9 @@ export interface Transaction {
   account: string;
 }
 
+/**
+ * Module with various helper methods that don't fit in a particular category.
+ */
 export class Helpers {
   constructor(private readonly faker: Faker) {
     // Bind `this` so namespaced is working correctly
@@ -128,6 +131,8 @@ export class Helpers {
    *
    * @param array The array to select an element from.
    *
+   * @see faker.random.arrayElement()
+   *
    * @example
    * faker.helpers.randomize() // 'c'
    * faker.helpers.randomize([1, 2, 3]) // '2'
@@ -298,7 +303,7 @@ export class Helpers {
   /**
    * Repeats the given string the given number of times.
    *
-   * @param string The string to repeat.
+   * @param string The string to repeat. Defaults to `''`.
    * @param num The number of times to repeat it. Defaults to `0`.
    *
    * @example
@@ -421,9 +426,10 @@ export class Helpers {
    * @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)
+   * @example
+   * uniqueArray(faker.random.word, 50)
+   * uniqueArray(faker.definitions.name.first_name, 6)
+   * uniqueArray(["Hello", "World", "Goodbye"], 2)
    */
   uniqueArray<T>(source: T[] | (() => T), length: number): T[] {
     if (Array.isArray(source)) {
@@ -452,6 +458,12 @@ 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()`.
+   *
+   * @example
+   * faker.helpers.mustache('I found {{count}} instances of "{{word}}".', {
+   *   count: () => `${faker.datatype.number()}`,
+   *   word: "this word",
+   * }) // 'I found 57591 instances of "this word".'
    */
   mustache(
     str: string | undefined,

src/image.ts

@@ -30,9 +30,9 @@ export class Image {
   /**
    * Generates a random image url from one of the supported categories.
    *
-   * @param width The width of the image.
-   * @param height The height of the image.
-   * @param randomize Whether to randomize the image or not.
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
    * @example
    * faker.image.image() // 'http://placeimg.com/640/480/city'
@@ -79,7 +79,7 @@ export class Image {
    * @param width The width of the image. Defaults to `640`.
    * @param height The height of the image. Defaults to `480`.
    * @param category The category of the image. By default, a random one will be selected.
-   * @param randomize Whether to randomize the image or not.
+   * @param randomize Whether to randomize the image or not. Defaults to `false`.
    * @param https When true, return a `https` url. Otherwise, return a `http` url.
    *
    * @example
@@ -117,9 +117,9 @@ export class Image {
   /**
    * Generates a random abstract image url.
    *
-   * @param width The width of the image.
-   * @param height The height of the image.
-   * @param randomize Whether to randomize the image or not.
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
    * @example
    * faker.image.abstract() // 'http://placeimg.com/640/480/abstract'
@@ -133,9 +133,9 @@ export class Image {
   /**
    * Generates a random animal image url.
    *
-   * @param width The width of the image.
-   * @param height The height of the image.
-   * @param randomize Whether to randomize the image or not.
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
    * @example
    * faker.image.animals() // 'http://placeimg.com/640/480/animals'
@@ -149,9 +149,9 @@ export class Image {
   /**
    * Generates a random business image url.
    *
-   * @param width The width of the image.
-   * @param height The height of the image.
-   * @param randomize Whether to randomize the image or not.
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
    * @example
    * faker.image.business() // 'http://placeimg.com/640/480/business'
@@ -165,9 +165,9 @@ export class Image {
   /**
    * Generates a random cat image url.
    *
-   * @param width The width of the image.
-   * @param height The height of the image.
-   * @param randomize Whether to randomize the image or not.
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
    * @example
    * faker.image.cats() // 'http://placeimg.com/640/480/cats'
@@ -181,9 +181,9 @@ export class Image {
   /**
    * Generates a random city image url.
    *
-   * @param width The width of the image.
-   * @param height The height of the image.
-   * @param randomize Whether to randomize the image or not.
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
    * @example
    * faker.image.city() // 'http://placeimg.com/640/480/city'
@@ -197,9 +197,9 @@ export class Image {
   /**
    * Generates a random food image url.
    *
-   * @param width The width of the image.
-   * @param height The height of the image.
-   * @param randomize Whether to randomize the image or not.
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
    * @example
    * faker.image.food() // 'http://placeimg.com/640/480/food'
@@ -213,9 +213,9 @@ export class Image {
   /**
    * Generates a random nightlife image url.
    *
-   * @param width The width of the image.
-   * @param height The height of the image.
-   * @param randomize Whether to randomize the image or not.
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
    * @example
    * faker.image.nightlife() // 'http://placeimg.com/640/480/nightlife'
@@ -229,9 +229,9 @@ export class Image {
   /**
    * Generates a random fashion image url.
    *
-   * @param width The width of the image.
-   * @param height The height of the image.
-   * @param randomize Whether to randomize the image or not.
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
    * @example
    * faker.image.fashion() // 'http://placeimg.com/640/480/fashion'
@@ -245,9 +245,9 @@ export class Image {
   /**
    * Generates a random people image url.
    *
-   * @param width The width of the image.
-   * @param height The height of the image.
-   * @param randomize Whether to randomize the image or not.
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
    * @example
    * faker.image.people() // 'http://placeimg.com/640/480/people'
@@ -261,9 +261,9 @@ export class Image {
   /**
    * Generates a random nature image url.
    *
-   * @param width The width of the image.
-   * @param height The height of the image.
-   * @param randomize Whether to randomize the image or not.
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
    * @example
    * faker.image.nature() // 'http://placeimg.com/640/480/nature'
@@ -277,9 +277,9 @@ export class Image {
   /**
    * Generates a random sports image url.
    *
-   * @param width The width of the image.
-   * @param height The height of the image.
-   * @param randomize Whether to randomize the image or not.
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
    * @example
    * faker.image.sports() // 'http://placeimg.com/640/480/sports'
@@ -293,9 +293,9 @@ export class Image {
   /**
    * Generates a random technics image url.
    *
-   * @param width The width of the image.
-   * @param height The height of the image.
-   * @param randomize Whether to randomize the image or not.
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
    * @example
    * faker.image.technics() // 'http://placeimg.com/640/480/technics'
@@ -309,9 +309,9 @@ export class Image {
   /**
    * Generates a random transport image url.
    *
-   * @param width The width of the image.
-   * @param height The height of the image.
-   * @param randomize Whether to randomize the image or not.
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
    * @example
    * faker.image.transport() // 'http://placeimg.com/640/480/transport'
@@ -325,8 +325,8 @@ export class Image {
   /**
    * Generates a random data uri containing an svg image.
    *
-   * @param width The width of the image.
-   * @param height The height of the image.
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
    * @param color The color to use. Defaults to `grey`.
    *
    * @example

src/index.ts

@@ -162,7 +162,7 @@ export class Faker {
   /**
    * Set Faker's locale
    *
-   * @param locale
+   * @param locale The locale to set (e.g. `en` or `en_AU`, `en_AU_ocker`).
    */
   setLocale(locale: UsableLocale): void {
     this.locale = locale;

src/internet.ts

@@ -319,7 +319,7 @@ export class Internet {
   /**
    * Generates a random mac address.
    *
-   * @param sep The optional separator to use. Can be either `':'`, `'-'` or `''`. Defaults to `':'`
+   * @param sep The optional separator to use. Can be either `':'`, `'-'` or `''`. Defaults to `':'`.
    *
    * @example
    * faker.internet.mac() // '32:8e:2e:09:c6:05'
@@ -350,7 +350,7 @@ export class Internet {
    * @param len The length of the password to generate. Defaults to `15`.
    * @param memorable Whether the generated password should be memorable. Defaults to `false`.
    * @param pattern The pattern that all chars should match should match. Defaults to `/\w/`.
-   * @param prefix The prefix to use. Defaults to `''`
+   * @param prefix The prefix to use. Defaults to `''`.
    *
    * @example
    * faker.internet.password() // '89G1wJuBLbGziIs'

src/lorem.ts

@@ -22,7 +22,7 @@ export class Lorem {
   /**
    * Generates a word of a specified length.
    *
-   * @param length length of the word that should be returned. Defaults to a random length
+   * @param length length of the word that should be returned. Defaults to a random length.
    *
    * @example
    * faker.lorem.word() // 'temporibus'

src/mersenne.ts

@@ -19,7 +19,7 @@ export class Mersenne {
   }
 
   /**
-   * Generates a random number between [min, max)'.
+   * Generates a random number between `[min, max)`.
    *
    * @param max The maximum number. Defaults to `0`.
    * @param min The minimum number. Defaults to `32768`. Required if `max` is set.

src/name.ts

@@ -216,7 +216,7 @@ export class Name {
   /**
    * Return a random gender.
    *
-   * @param binary Whether to return only binary gender names. Defaults to false.
+   * @param binary Whether to return only binary gender names. Defaults to `false`.
    *
    * @example
    * faker.name.gender() // 'Trans*Man'