docs: fix missing or invalid jsdocs (#2630)

3 files changed, 35 insertions, 6 deletions

diff --git a/src/faker.ts b/src/faker.ts
index f43b9c36..97a513d0 100644
--- a/src/faker.ts
+++ b/src/faker.ts
@@ -140,6 +140,8 @@ export class Faker extends SimpleFaker {
    * customFaker.person.lastName(); // 'Ocampo Corrales'
    *
    * customFaker.music.genre(); // throws Error as this data is not available in `es`
+   *
+   * @since 8.0.0
    */
   constructor(options: {
     /**
@@ -173,6 +175,11 @@ export class Faker extends SimpleFaker {
    * @param options.locale The name of the main locale to use.
    * @param options.localeFallback The name of the fallback locale to use.
    *
+   * @example
+   * new Faker({ locales: allLocales });
+   *
+   * @since 6.0.0
+   *
    * @deprecated Use `new Faker({ locale: [locale, localeFallback] })` instead.
    */
   constructor(options: {
@@ -210,6 +217,8 @@ export class Faker extends SimpleFaker {
    * customFaker.person.lastName(); // 'Ocampo Corrales'
    *
    * customFaker.music.genre(); // throws Error as this data is not available in `es`
+   *
+   * @since 8.0.0
    */
   constructor(
     options:
@@ -317,6 +326,8 @@ export class Faker extends SimpleFaker {
    * // const { faker, fakerES_MX } = require("@faker-js/faker")
    * faker.getMetadata(); // { title: 'English', code: 'en', language: 'en', endonym: 'English', dir: 'ltr', script: 'Latn' }
    * fakerES_MX.getMetadata(); // { title: 'Spanish (Mexico)', code: 'es_MX', language: 'es', endonym: 'Español (México)', dir: 'ltr', script: 'Latn', country: 'MX' }
+   *
+   * @since 8.1.0
    */
   getMetadata(): MetadataDefinition {
     return this.rawDefinitions.metadata ?? {};
diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts
index 0bd679cc..0c94317b 100644
--- a/src/modules/location/index.ts
+++ b/src/modules/location/index.ts
@@ -623,10 +623,9 @@ export class LocationModule extends ModuleBase {
   /**
    * Generates a random longitude.
    *
-   * @param options An options object.
-   * @param options.max The upper bound for the longitude to generate. Defaults to `180`.
-   * @param options.min The lower bound for the longitude to generate. Defaults to `-180`.
-   * @param options.precision The number of decimal points of precision for the longitude. Defaults to `4`.
+   * @param max The upper bound for the longitude to generate. Defaults to `180`.
+   * @param min The lower bound for the longitude to generate. Defaults to `-180`.
+   * @param precision The number of decimal points of precision for the longitude. Defaults to `4`.
    *
    * @example
    * faker.location.longitude() // -30.9501
@@ -992,8 +991,7 @@ export class LocationModule extends ModuleBase {
   /**
    * Returns a random ordinal direction (northwest, southeast, etc).
    *
-   * @param options Whether to use abbreviated or an options object.
-   * @param options.abbreviated If true this will return abbreviated directions (NW, SE, etc).
+   * @param abbreviated If true this will return abbreviated directions (NW, SE, etc).
    * Otherwise this will return the long name. Defaults to `false`.
    *
    * @example
diff --git a/src/simple-faker.ts b/src/simple-faker.ts
index b6fb3475..4dd755e1 100644
--- a/src/simple-faker.ts
+++ b/src/simple-faker.ts
@@ -65,6 +65,8 @@ export class SimpleFaker {
    *
    * faker.defaultRefDate() // 2020-01-01T00:00:01Z
    * faker.defaultRefDate() // 2020-01-01T00:00:02Z
+   *
+   * @since 8.0.0
    */
   setDefaultRefDate(
     dateOrSource: string | Date | number | (() => Date) = () => new Date()
@@ -95,6 +97,18 @@ export class SimpleFaker {
    * Specify this only if you want to use it to achieve a specific goal,
    * such as sharing the same random generator with other instances/tools.
    * Defaults to faker's Mersenne Twister based pseudo random number generator.
+   *
+   * @example
+   * import { SimpleFaker } from '@faker-js/faker';
+   * // const { SimpleFaker } = require('@faker-js/faker');
+   *
+   * // create a SimpleFaker without any locale data
+   * const customSimpleFaker = new SimpleFaker();
+   *
+   * customSimpleFaker.helpers.arrayElement([red', 'green', 'blue']); // 'green'
+   * customSimpleFaker.number.int(10); // 4
+   *
+   * @since 8.1.0
    */
   constructor(
     options: {
@@ -146,6 +160,8 @@ export class SimpleFaker {
    * // 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());
+   *
+   * @since 6.0.0
    */
   seed(seed?: number): number;
   /**
@@ -181,6 +197,8 @@ export class SimpleFaker {
    * // 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());
+   *
+   * @since 6.0.0
    */
   seed(seedArray: number[]): number[];
   /**
@@ -225,6 +243,8 @@ export class SimpleFaker {
    * // 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());
+   *
+   * @since 6.0.0
    */
   seed(seed?: number | number[]): number | number[];
   seed(