docs: extend Faker class jsdocs (#1960)

Author: ST-DDT

src/faker.ts

@@ -33,6 +33,32 @@ import { VehicleModule } from './modules/vehicle';
 import { WordModule } from './modules/word';
 import { mergeLocales } from './utils/merge-locales';
 
+/**
+ * The is Faker's main class containing all modules that can be used to generate data.
+ *
+ * Please have a look at the individual modules and methods for more information and examples.
+ *
+ * @example
+ * import { faker } from '@faker-js/faker';
+ * // const { faker } = require('@faker-js/faker');
+ *
+ * // faker.seed(1234);
+ *
+ * faker.person.firstName(); // 'John'
+ * faker.person.lastName(); // 'Doe'
+ *
+ * @example
+ * import { Faker, es } from '@faker-js/faker';
+ * // const { Faker, es } = require('@faker-js/faker');
+ *
+ * // create a Faker instance with only es data and no en fallback (=> smaller bundle size)
+ * const customFaker = new Faker({ locale: [es] });
+ *
+ * customFaker.person.firstName(); // 'Javier'
+ * customFaker.person.lastName(); // 'Ocampo Corrales'
+ *
+ * customFaker.music.genre(); // throws Error as this data is not available in `es`
+ */
 export class Faker {
   readonly definitions: LocaleDefinition;
   private _defaultRefDate: () => Date = () => new Date();
@@ -50,6 +76,30 @@ export class Faker {
    * @param dateOrSource The function or the static value used to generate the `refDate` date instance.
    * The function must return a new valid `Date` instance for every call.
    * Defaults to `() => new Date()`.
+   *
+   * @see [Reproducible Results](https://next.fakerjs.dev/guide/usage.html#reproducible-results)
+   * @see faker.seed() for reproducible results.
+   *
+   * @example
+   * faker.seed(1234);
+   *
+   * // Default behavior
+   * // faker.setDefaultRefDate();
+   * faker.date.past(); // Changes based on the current date/time
+   *
+   * // Use a static ref date
+   * faker.setDefaultRefDate(new Date('2020-01-01'));
+   * faker.date.past(); // Reproducible '2019-07-03T08:27:58.118Z'
+   *
+   * // Use a ref date that changes every time it is used
+   * let clock = new Date("2020-01-01").getTime();
+   * faker.setDefaultRefDate(() => {
+   *   clock += 1000; // +1s
+   *   return new Date(clock);
+   * });
+   *
+   * faker.defaultRefDate() // 2020-01-01T00:00:01Z
+   * faker.defaultRefDate() // 2020-01-01T00:00:02Z
    */
   setDefaultRefDate(
     dateOrSource: string | Date | number | (() => Date) = () => new Date()
@@ -124,8 +174,26 @@ export class Faker {
   /**
    * Creates a new instance of Faker.
    *
+   * In most cases you should use one of the prebuilt Faker instances instead of the constructor, for example `fakerDE`, `fakerFR`, ...
+   *
+   * You only need to use the constructor if you need custom fallback logic or a custom locale.
+   *
+   * For more information see our [Localization Guide](https://next.fakerjs.dev/guide/localization.html).
+   *
    * @param options The options to use.
    * @param options.locale The locale data to use.
+   *
+   * @example
+   * import { Faker, es } from '@faker-js/faker';
+   * // const { Faker, es } = require('@faker-js/faker');
+   *
+   * // create a Faker instance with only es data and no en fallback (=> smaller bundle size)
+   * const customFaker = new Faker({ locale: [es] });
+   *
+   * customFaker.person.firstName(); // 'Javier'
+   * customFaker.person.lastName(); // 'Ocampo Corrales'
+   *
+   * customFaker.music.genre(); // throws Error as this data is not available in `es`
    */
   constructor(options: {
     /**
@@ -139,9 +207,16 @@ export class Faker {
   /**
    * Creates a new instance of Faker.
    *
+   * In most cases you should use one of the prebuilt Faker instances instead of the constructor, for example `fakerDE`, `fakerFR`, ...
+   *
+   * You only need to use the constructor if you need custom fallback logic or a custom locale.
+   *
+   * For more information see our [Localization Guide](https://next.fakerjs.dev/guide/localization.html).
+   *
    * @param options The options to use.
    * @param options.locales The locale data to use.
-   * @param options.locale The locale data to use.
+   * @param options.locale The name of the main locale to use.
+   * @param options.localeFallback The name of the fallback locale to use.
    *
    * @deprecated Use `new Faker({ locale: [locale, localeFallback] })` instead.
    */
@@ -151,12 +226,65 @@ export class Faker {
     localeFallback?: string;
   });
   // This is somehow required for `ConstructorParameters<typeof Faker>[0]` to work
+  /**
+   * Creates a new instance of Faker.
+   *
+   * In most cases you should use one of the prebuilt Faker instances instead of the constructor, for example `fakerDE`, `fakerFR`, ...
+   *
+   * You only need to use the constructor if you need custom fallback logic or a custom locale.
+   *
+   * For more information see our [Localization Guide](https://next.fakerjs.dev/guide/localization.html).
+   *
+   * @param options The options to use.
+   * @param options.locale The locale data to use or the name of the main locale.
+   * @param options.locales The locale data to use.
+   * @param options.localeFallback The name of the fallback locale to use.
+   *
+   * @example
+   * import { Faker, es } from '@faker-js/faker';
+   * // const { Faker, es } = require('@faker-js/faker');
+   *
+   * // create a Faker instance with only es data and no en fallback (=> smaller bundle size)
+   * const customFaker = new Faker({ locale: [es] });
+   *
+   * customFaker.person.firstName(); // 'Javier'
+   * customFaker.person.lastName(); // 'Ocampo Corrales'
+   *
+   * customFaker.music.genre(); // throws Error as this data is not available in `es`
+   */
   constructor(
     options:
-      | { locale: LocaleDefinition | LocaleDefinition[] }
       | {
+          /**
+           * The locale data to use for this instance.
+           * If an array is provided, the first locale that has a definition for a given property will be used.
+           *
+           * @see mergeLocales
+           */
+          locale: LocaleDefinition | LocaleDefinition[];
+        }
+      | {
+          /**
+           * The locale data to use for this instance.
+           *
+           * @deprecated Use `new Faker({ locale: [locale, localeFallback] })` instead.
+           */
           locales: Record<string, LocaleDefinition>;
+          /**
+           * The name of the main locale to use.
+           *
+           * @default 'en'
+           *
+           * @deprecated Use `new Faker({ locale: [locale, localeFallback] })` instead.
+           */
           locale?: string;
+          /**
+           * The name of the fallback locale to use.
+           *
+           * @default 'en'
+           *
+           * @deprecated Use `new Faker({ locale: [locale, localeFallback] })` instead.
+           */
           localeFallback?: string;
         }
   );
@@ -221,6 +349,9 @@ export class Faker {
    * @param seed The seed to use. Defaults to a random number.
    * @returns The seed that was set.
    *
+   * @see [Reproducible Results](https://next.fakerjs.dev/guide/usage.html#reproducible-results)
+   * @see faker.setDefaultRefDate() when generating relative dates.
+   *
    * @example
    * // Consistent values for tests:
    * faker.seed(42)
@@ -231,7 +362,6 @@ export class Faker {
    * faker.number.int(10); // 4
    * faker.number.int(10); // 8
    *
-   * @example
    * // Random but reproducible tests:
    * // Simply log the seed, and if you need to reproduce it, insert the seed here
    * console.log('Running test with seed:', faker.seed());
@@ -253,6 +383,9 @@ export class Faker {
    * @param seedArray The seed array to use.
    * @returns The seed array that was set.
    *
+   * @see [Reproducible Results](https://next.fakerjs.dev/guide/usage.html#reproducible-results)
+   * @see faker.setDefaultRefDate() when generating relative dates.
+   *
    * @example
    * // Consistent values for tests:
    * faker.seed([42, 13, 17])
@@ -263,12 +396,54 @@ export class Faker {
    * faker.number.int(10); // 4
    * faker.number.int(10); // 8
    *
-   * @example
    * // Random but reproducible tests:
    * // Simply log the seed, and if you need to reproduce it, insert the seed here
    * console.log('Running test with seed:', faker.seed());
    */
   seed(seedArray: number[]): number[];
+  /**
+   * Sets the seed or generates a new one.
+   *
+   * Please note that generated values are dependent on both the seed and the
+   * number of calls that have been made since it was set.
+   *
+   * This method is intended to allow for consistent values in a tests, so you
+   * might want to use hardcoded values as the seed.
+   *
+   * In addition to that it can be used for creating truly random tests
+   * (by passing no arguments), that still can be reproduced if needed,
+   * by logging the result and explicitly setting it if needed.
+   *
+   * @param seed The seed or seed array to use.
+   * @returns The seed that was set.
+   *
+   * @see [Reproducible Results](https://next.fakerjs.dev/guide/usage.html#reproducible-results)
+   * @see faker.setDefaultRefDate() when generating relative dates.
+   *
+   * @example
+   * // Consistent values for tests (using a number):
+   * faker.seed(42)
+   * faker.number.int(10); // 4
+   * faker.number.int(10); // 8
+   *
+   * faker.seed(42)
+   * faker.number.int(10); // 4
+   * faker.number.int(10); // 8
+   *
+   * // Consistent values for tests (using an array):
+   * faker.seed([42, 13, 17])
+   * faker.number.int(10); // 4
+   * faker.number.int(10); // 8
+   *
+   * faker.seed([42, 13, 17])
+   * faker.number.int(10); // 4
+   * faker.number.int(10); // 8
+   *
+   * // Random but reproducible tests:
+   * // Simply log the seed, and if you need to reproduce it, insert the seed here
+   * console.log('Running test with seed:', faker.seed());
+   */
+  seed(seed?: number | number[]): number | number[];
   seed(
     seed: number | number[] = Math.ceil(Math.random() * Number.MAX_SAFE_INTEGER)
   ): number | number[] {