docs: fix missing or invalid jsdocs (#2630)

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 ?? {};

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

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(