From 6bd0c1d29eeac4e9e1cc64d9b342183e70d23b80 Mon Sep 17 00:00:00 2001
From: ST-DDT <ST-DDT@gmx.de>
Date: Thu, 12 Oct 2023 18:06:49 +0200
Subject: [PATCH 01/11] docs: consistent @see jsdoc tags

---
 src/definitions/finance.ts                    |  2 +-
 src/definitions/hacker.ts                     |  2 +-
 src/definitions/phone_number.ts               |  2 +-
 src/faker.ts                                  |  4 +-
 src/modules/company/index.ts                  |  4 +-
 src/modules/datatype/index.ts                 | 19 +++----
 src/modules/date/index.ts                     | 30 +++++------
 src/modules/finance/index.ts                  | 10 ++--
 src/modules/helpers/index.ts                  |  8 +--
 src/modules/image/index.ts                    | 52 +++++++++----------
 src/modules/internet/index.ts                 | 12 ++---
 src/modules/location/index.ts                 |  8 +--
 src/modules/number/index.ts                   |  6 +--
 src/modules/person/index.ts                   | 10 ++--
 src/modules/random/index.ts                   | 14 ++---
 src/modules/string/index.ts                   |  6 +--
 src/simple-faker.ts                           |  8 +--
 test/scripts/apidoc/verify-jsdoc-tags.spec.ts |  8 +++
 18 files changed, 109 insertions(+), 96 deletions(-)

diff --git a/src/definitions/finance.ts b/src/definitions/finance.ts
index d98edd1a422..ecccb9370e0 100644
--- a/src/definitions/finance.ts
+++ b/src/definitions/finance.ts
@@ -13,7 +13,7 @@ export type FinanceDefinition = LocaleEntry<{
    * The pattern by (lowercase) issuer name used to generate credit card codes.
    * `L` will be replaced by the check bit.
    *
-   * @see faker.helpers.replaceCreditCardSymbols()
+   * @see faker.helpers.replaceCreditCardSymbols(): For more information about the how the pattern is used.
    */
   credit_card: { [issuer: string]: string[] };
 
diff --git a/src/definitions/hacker.ts b/src/definitions/hacker.ts
index f3630100bd3..a5a2dc89eb9 100644
--- a/src/definitions/hacker.ts
+++ b/src/definitions/hacker.ts
@@ -29,7 +29,7 @@ export type HackerDefinition = LocaleEntry<{
    * May use any of the HackerDefinition keys wrapped in double braces
    * (e.g. `I'm {{ingverb}} {{adjective}} {{noun}}`).
    *
-   * @see faker.helpers.mustache()
+   * @see faker.helpers.mustache(): For more information about how the phrases are generated.
    */
   phrase: string[];
 
diff --git a/src/definitions/phone_number.ts b/src/definitions/phone_number.ts
index fd6a8baa47e..f321c9bda1b 100644
--- a/src/definitions/phone_number.ts
+++ b/src/definitions/phone_number.ts
@@ -10,7 +10,7 @@ export type PhoneNumberDefinition = LocaleEntry<{
    * `!` will be replaced by a random digit (2-9).
    * (e.g. `!##-!##-####` -> 272-285-0453)
    *
-   * @see faker.helpers.replaceSymbolWithNumber(format)
+   * @see faker.helpers.replaceSymbolWithNumber(format): For more information about the how the patterns are used.
    */
   formats: string[];
 }>;
diff --git a/src/faker.ts b/src/faker.ts
index e6b5889af36..ccda9a4c135 100644
--- a/src/faker.ts
+++ b/src/faker.ts
@@ -146,7 +146,7 @@ export class Faker extends SimpleFaker {
      * 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
+     * @see mergeLocales() For more information about how the locales are merged.
      */
     locale: LocaleDefinition | LocaleDefinition[];
 
@@ -218,7 +218,7 @@ export class Faker extends SimpleFaker {
            * 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
+           * @see mergeLocales() For more information about how the locales are merged.
            */
           locale: LocaleDefinition | LocaleDefinition[];
 
diff --git a/src/modules/company/index.ts b/src/modules/company/index.ts
index c24ea7f3b6b..fe87c7fc4a8 100644
--- a/src/modules/company/index.ts
+++ b/src/modules/company/index.ts
@@ -24,7 +24,7 @@ export class CompanyModule {
   /**
    * Returns an array with possible company name suffixes.
    *
-   * @see faker.company.name()
+   * @see faker.company.name(): For a method that returns a complete company name.
    *
    * @example
    * faker.company.suffixes() // [ 'Inc', 'and Sons', 'LLC', 'Group' ]
@@ -60,7 +60,7 @@ export class CompanyModule {
   /**
    * Returns a random company suffix.
    *
-   * @see faker.company.name()
+   * @see faker.company.name(): For a method that returns a complete company name.
    *
    * @example
    * faker.company.companySuffix() // 'and Sons'
diff --git a/src/modules/datatype/index.ts b/src/modules/datatype/index.ts
index 4043d6c5433..de6f9a9397c 100644
--- a/src/modules/datatype/index.ts
+++ b/src/modules/datatype/index.ts
@@ -27,8 +27,8 @@ export class DatatypeModule {
    *
    * @throws When options define `max < min`.
    *
-   * @see faker.number.int() for the default precision of `1`
-   * @see faker.number.float() for a custom precision
+   * @see faker.number.int(): For the new method when generating a random integer.
+   * @see faker.number.float(): For the new method when generating a random floating-point number.
    *
    * @example
    * faker.datatype.number() // 55422
@@ -90,7 +90,7 @@ export class DatatypeModule {
    * @param options.max Upper bound for generated number. Defaults to `min + 99999`.
    * @param options.precision Precision of the generated number. Defaults to `0.01`.
    *
-   * @see faker.number.float()
+   * @see faker.number.float(): For the new method when generating a random floating-point number.
    *
    * @example
    * faker.datatype.float() // 51696.36
@@ -158,8 +158,8 @@ export class DatatypeModule {
    *    When not provided or larger than `8640000000000000`, `2100-01-01` is considered
    *    as maximum generated date. Defaults to `4102444800000`.
    *
-   * @see faker.date.anytime()
-   * @see faker.date.between()
+   * @see faker.date.anytime(): For the new method when generating a random date in either the past or future.
+   * @see faker.date.between(): For the new method when generating a random date between the two dates.
    *
    * @example
    * faker.datatype.datetime() // '2089-04-17T18:03:24.956Z'
@@ -221,7 +221,7 @@ export class DatatypeModule {
    * @param options Length of the generated string or an options object. Defaults to `{}`.
    * @param options.length Length of the generated string. Max length is `2^20`. Defaults to `10`.
    *
-   * @see faker.string.sample()
+   * @see faker.string.sample(): For the new method when generating a random string.
    *
    * @example
    * faker.datatype.string() // 'Zo!.:*e>wR'
@@ -262,7 +262,7 @@ export class DatatypeModule {
   /**
    * Returns a UUID v4 ([Universally Unique Identifier](https://en.wikipedia.org/wiki/Universally_unique_identifier)).
    *
-   * @see faker.string.uuid()
+   * @see faker.string.uuid(): For the new method when generating a random UUID.
    *
    * @example
    * faker.datatype.uuid() // '4136cd0b-d90b-4af7-b485-5d1ded8db252'
@@ -339,7 +339,8 @@ export class DatatypeModule {
    * @param options.prefix Prefix for the generated number. Defaults to `'0x'`.
    * @param options.case Case of the generated number. Defaults to `'mixed'`.
    *
-   * @see faker.string.hexadecimal()
+   * @see faker.string.hexadecimal(): For the new method when generating a random hexadecimal string.
+   * @see faker.number.hex(): For the new method when generating a random hexadecimal number.
    *
    * @example
    * faker.datatype.hexadecimal() // '0xB'
@@ -469,7 +470,7 @@ export class DatatypeModule {
    *
    * @throws When options define `max < min`.
    *
-   * @see faker.number.bigInt()
+   * @see faker.number.bigInt(): For the new method when generating a random bigint.
    *
    * @example
    * faker.datatype.bigInt() // 55422n
diff --git a/src/modules/date/index.ts b/src/modules/date/index.ts
index 8f7efaaeed4..e42d54efea3 100644
--- a/src/modules/date/index.ts
+++ b/src/modules/date/index.ts
@@ -37,9 +37,9 @@ export class SimpleDateModule {
    * @param options The optional options object.
    * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
-   * @see faker.date.between() For dates in a specific range.
-   * @see faker.date.past() For dates explicitly in the past.
-   * @see faker.date.future() For dates explicitly in the future.
+   * @see faker.date.between(): For dates in a specific range.
+   * @see faker.date.past(): For dates explicitly in the past.
+   * @see faker.date.future(): For dates explicitly in the future.
    *
    * @example
    * faker.date.anytime() // '2022-07-31T01:33:29.567Z'
@@ -73,7 +73,7 @@ export class SimpleDateModule {
    * @param options.years The range of years the date may be in the past. Defaults to `1`.
    * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
-   * @see faker.date.recent()
+   * @see faker.date.recent(): For dates in the recent past (days instead of years).
    *
    * @example
    * faker.date.past() // '2021-12-03T05:40:44.408Z'
@@ -102,7 +102,7 @@ export class SimpleDateModule {
    * @param years The range of years the date may be in the past. Defaults to `1`.
    * @param refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
-   * @see faker.date.recent()
+   * @see faker.date.recent(): For dates in the recent past (days instead of years).
    *
    * @example
    * faker.date.past() // '2021-12-03T05:40:44.408Z'
@@ -122,7 +122,7 @@ export class SimpleDateModule {
    * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    * @param legacyRefDate Deprecated, use `options.refDate` instead.
    *
-   * @see faker.date.recent()
+   * @see faker.date.recent(): For dates in the recent past (days instead of years).
    *
    * @example
    * faker.date.past() // '2021-12-03T05:40:44.408Z'
@@ -195,7 +195,7 @@ export class SimpleDateModule {
    * @param options.years The range of years the date may be in the future. Defaults to `1`.
    * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
-   * @see faker.date.soon()
+   * @see faker.date.soon(): For dates in the near future (days instead of years).
    *
    * @example
    * faker.date.future() // '2022-11-19T05:52:49.100Z'
@@ -224,7 +224,7 @@ export class SimpleDateModule {
    * @param years The range of years the date may be in the future. Defaults to `1`.
    * @param refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
-   * @see faker.date.soon()
+   * @see faker.date.soon(): For dates in the near future (days instead of years).
    *
    * @example
    * faker.date.future() // '2022-11-19T05:52:49.100Z'
@@ -244,7 +244,7 @@ export class SimpleDateModule {
    * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    * @param legacyRefDate Deprecated, use `options.refDate` instead.
    *
-   * @see faker.date.soon()
+   * @see faker.date.soon(): For dates in the near future (days instead of years).
    *
    * @example
    * faker.date.future() // '2022-11-19T05:52:49.100Z'
@@ -587,7 +587,7 @@ export class SimpleDateModule {
    * @param options.days The range of days the date may be in the past. Defaults to `1`.
    * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
-   * @see faker.date.past()
+   * @see faker.date.past(): For dates further back in time (years instead of days).
    *
    * @example
    * faker.date.recent() // '2022-02-04T02:09:35.077Z'
@@ -616,7 +616,7 @@ export class SimpleDateModule {
    * @param days The range of days the date may be in the past. Defaults to `1`.
    * @param refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
-   * @see faker.date.past()
+   * @see faker.date.past(): For dates further back in time (years instead of days).
    *
    * @example
    * faker.date.recent() // '2022-02-04T02:09:35.077Z'
@@ -636,7 +636,7 @@ export class SimpleDateModule {
    * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    * @param legacyRefDate Deprecated, use `options.refDate` instead.
    *
-   * @see faker.date.past()
+   * @see faker.date.past(): For dates further back in time (years instead of days).
    *
    * @example
    * faker.date.recent() // '2022-02-04T02:09:35.077Z'
@@ -704,7 +704,7 @@ export class SimpleDateModule {
    * @param options.days The range of days the date may be in the future. Defaults to `1`.
    * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
-   * @see faker.date.future()
+   * @see faker.date.future(): For dates further in the future (years instead of days).
    *
    * @example
    * faker.date.soon() // '2022-02-05T09:55:39.216Z'
@@ -733,7 +733,7 @@ export class SimpleDateModule {
    * @param days The range of days the date may be in the future. Defaults to `1`.
    * @param refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
-   * @see faker.date.future()
+   * @see faker.date.future(): For dates further in the future (years instead of days).
    *
    * @example
    * faker.date.soon() // '2022-02-05T09:55:39.216Z'
@@ -753,7 +753,7 @@ export class SimpleDateModule {
    * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    * @param legacyRefDate Deprecated, use `options.refDate` instead.
    *
-   * @see faker.date.future()
+   * @see faker.date.future(): For dates further in the future (years instead of days).
    *
    * @example
    * faker.date.soon() // '2022-02-05T09:55:39.216Z'
diff --git a/src/modules/finance/index.ts b/src/modules/finance/index.ts
index 43cd16a1c5e..e7e692c4f41 100644
--- a/src/modules/finance/index.ts
+++ b/src/modules/finance/index.ts
@@ -47,7 +47,7 @@ export class FinanceModule {
    *
    * @param length The length of the account number. Defaults to `8`.
    *
-   * @see faker.finance.accountNumber()
+   * @see faker.finance.accountNumber(): For the new method that replaces this one.
    *
    * @example
    * faker.finance.account() // 92842238
@@ -209,7 +209,7 @@ export class FinanceModule {
    * @param parens Whether to use surrounding parenthesis. Defaults to `true`.
    * @param ellipsis Whether to prefix the numbers with an ellipsis. Defaults to `true`.
    *
-   * @see faker.finance.maskedNumber()
+   * @see faker.finance.maskedNumber(): For the new method that replaces this one.
    *
    * @example
    * faker.finance.mask() // '(...9711)'
@@ -629,9 +629,9 @@ export class FinanceModule {
    * Returns a random currency object, containing `code`, `name `and `symbol` properties.
    *
    * @see
-   * faker.finance.currencyCode()
-   * faker.finance.currencyName()
-   * faker.finance.currencySymbol()
+   * faker.finance.currencyCode(): For a method that returns specifically the currency code.
+   * faker.finance.currencyName(): For a method that returns specifically the currency name.
+   * faker.finance.currencySymbol(): For a method that returns specifically the currency symbol.
    *
    * @example
    * faker.finance.currency() // { code: 'USD', name: 'US Dollar', symbol: '$' }
diff --git a/src/modules/helpers/index.ts b/src/modules/helpers/index.ts
index 7548c15b578..d1b2ddeb57b 100644
--- a/src/modules/helpers/index.ts
+++ b/src/modules/helpers/index.ts
@@ -329,7 +329,7 @@ export class SimpleHelpersModule {
    *
    * @param string The template string to parse.
    *
-   * @see faker.helpers.fromRegExp()
+   * @see faker.helpers.fromRegExp(): Generates a string matching the given regex like expressions.
    *
    * @example
    * faker.helpers.regexpStyleStringParse() // ''
@@ -1293,7 +1293,7 @@ export class HelpersModule extends SimpleHelpersModule {
    *
    * @param pattern The pattern string that will get interpolated.
    *
-   * @see faker.helpers.mustache() to use custom functions for resolution.
+   * @see faker.helpers.mustache(): If you wish to use custom functions for resolution.
    *
    * @example
    * faker.helpers.fake('{{person.lastName}}') // 'Barrows'
@@ -1345,7 +1345,7 @@ export class HelpersModule extends SimpleHelpersModule {
    *
    * @param patterns The array to select a pattern from, that will then get interpolated. Must not be empty.
    *
-   * @see faker.helpers.mustache() to use custom functions for resolution.
+   * @see faker.helpers.mustache(): If you wish to use custom functions for resolution.
    *
    * @example
    * faker.helpers.fake(['A: {{person.firstName}}', 'B: {{person.lastName}}']) // 'A: Barry'
@@ -1388,7 +1388,7 @@ export class HelpersModule extends SimpleHelpersModule {
    *
    * @param pattern The pattern string that will get interpolated. If an array is passed, a random element will be picked and interpolated.
    *
-   * @see faker.helpers.mustache() to use custom functions for resolution.
+   * @see faker.helpers.mustache(): If you wish to use custom functions for resolution.
    *
    * @example
    * faker.helpers.fake('{{person.lastName}}') // 'Barrows'
diff --git a/src/modules/image/index.ts b/src/modules/image/index.ts
index a93f181e131..8403eee421b 100644
--- a/src/modules/image/index.ts
+++ b/src/modules/image/index.ts
@@ -508,8 +508,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url()
-   * @see faker.image.urlLoremFlickr()
+   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
    * faker.image.abstract() // 'https://loremflickr.com/640/480/abstract'
@@ -540,8 +540,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url()
-   * @see faker.image.urlLoremFlickr()
+   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
    * faker.image.animals() // 'https://loremflickr.com/640/480/animals'
@@ -572,8 +572,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url()
-   * @see faker.image.urlLoremFlickr()
+   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
    * faker.image.business() // 'https://loremflickr.com/640/480/business'
@@ -605,8 +605,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url()
-   * @see faker.image.urlLoremFlickr()
+   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
    * faker.image.cats() // 'https://loremflickr.com/640/480/cats'
@@ -636,8 +636,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url()
-   * @see faker.image.urlLoremFlickr()
+   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
    * faker.image.city() // 'https://loremflickr.com/640/480/city'
@@ -667,8 +667,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url()
-   * @see faker.image.urlLoremFlickr()
+   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
    * faker.image.food() // 'https://loremflickr.com/640/480/food'
@@ -698,8 +698,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url()
-   * @see faker.image.urlLoremFlickr()
+   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
    * faker.image.nightlife() // 'https://loremflickr.com/640/480/nightlife'
@@ -729,8 +729,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url()
-   * @see faker.image.urlLoremFlickr()
+   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
    * faker.image.fashion() // 'https://loremflickr.com/640/480/fashion'
@@ -760,8 +760,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url()
-   * @see faker.image.urlLoremFlickr()
+   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
    * faker.image.people() // 'https://loremflickr.com/640/480/people'
@@ -791,8 +791,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url()
-   * @see faker.image.urlLoremFlickr()
+   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
    * faker.image.nature() // 'https://loremflickr.com/640/480/nature'
@@ -822,8 +822,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url()
-   * @see faker.image.urlLoremFlickr()
+   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
    * faker.image.sports() // 'https://loremflickr.com/640/480/sports'
@@ -853,8 +853,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url()
-   * @see faker.image.urlLoremFlickr()
+   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
    * faker.image.technics() // 'https://loremflickr.com/640/480/technics'
@@ -884,8 +884,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url()
-   * @see faker.image.urlLoremFlickr()
+   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
    * faker.image.transport() // 'https://loremflickr.com/640/480/transport'
diff --git a/src/modules/internet/index.ts b/src/modules/internet/index.ts
index 6e8f822f22f..3d359bc5254 100644
--- a/src/modules/internet/index.ts
+++ b/src/modules/internet/index.ts
@@ -486,7 +486,7 @@ export class InternetModule {
    * @param options.firstName The optional first name to use. If not specified, a random one will be chosen.
    * @param options.lastName The optional last name to use. If not specified, a random one will be chosen.
    *
-   * @see faker.internet.displayName()
+   * @see faker.internet.displayName(): If you wish to generate a Unicode display name.
    *
    * @example
    * faker.internet.userName() // 'Nettie_Zboncak40'
@@ -521,7 +521,7 @@ export class InternetModule {
    * @param firstName The optional first name to use. If not specified, a random one will be chosen.
    * @param lastName The optional last name to use. If not specified, a random one will be chosen.
    *
-   * @see faker.internet.displayName()
+   * @see faker.internet.displayName(): If you wish to generate a Unicode display name.
    *
    * @example
    * faker.internet.userName() // 'Nettie_Zboncak40'
@@ -547,7 +547,7 @@ export class InternetModule {
    * @param options.lastName The optional last name to use. If not specified, a random one will be chosen.
    * @param legacyLastName The optional last name to use. If not specified, a random one will be chosen.
    *
-   * @see faker.internet.displayName()
+   * @see faker.internet.displayName(): If you wish to generate a Unicode display name.
    *
    * @example
    * faker.internet.userName() // 'Nettie_Zboncak40'
@@ -671,7 +671,7 @@ export class InternetModule {
    * @param options.firstName The optional first name to use. If not specified, a random one will be chosen.
    * @param options.lastName The optional last name to use. If not specified, a random one will be chosen.
    *
-   * @see faker.internet.userName()
+   * @see faker.internet.userName(): If you wish to generate a plain ASCII username.
    *
    * @example
    * faker.internet.displayName() // 'Nettie_Zboncak40'
@@ -706,7 +706,7 @@ export class InternetModule {
    * @param firstName The optional first name to use. If not specified, a random one will be chosen.
    * @param lastName The optional last name to use. If not specified, a random one will be chosen.
    *
-   * @see faker.internet.userName()
+   * @see faker.internet.userName(): If you wish to generate a plain ASCII username.
    *
    * @example
    * faker.internet.displayName() // 'Nettie_Zboncak40'
@@ -732,7 +732,7 @@ export class InternetModule {
    * @param options.lastName The optional last name to use. If not specified, a random one will be chosen.
    * @param legacyLastName The optional last name to use. If not specified, a random one will be chosen.
    *
-   * @see faker.internet.userName()
+   * @see faker.internet.userName(): If you wish to generate a plain ASCII username.
    *
    * @example
    * faker.internet.displayName() // 'Nettie_Zboncak40'
diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts
index 19816c8fd67..5d50eb1bdd6 100644
--- a/src/modules/location/index.ts
+++ b/src/modules/location/index.ts
@@ -30,7 +30,7 @@ export class LocationModule {
    * By default, a random format is used from the locale zip formats.
    * This won't be used if the state option is specified.
    *
-   * @see faker.helpers.replaceSymbols()
+   * @see faker.helpers.replaceSymbols(): For more information about how the pattern is used.
    *
    * @example
    * faker.location.zipCode() // '17839'
@@ -94,7 +94,7 @@ export class LocationModule {
    * @param options.state The abbreviation of the state to generate the zip code for.
    * If not specified, a random zip code is generated according to the locale's zip format.
    *
-   * @see faker.location.zipCode()
+   * @see faker.location.zipCode(): For the new method that replaces this one.
    *
    * @example
    * fakerEN_US.location.zipCodeByState("AK") // '99595'
@@ -150,7 +150,7 @@ export class LocationModule {
   /**
    * Returns a random city name from a list of real cities for the locale.
    *
-   * @see faker.location.city()
+   * @see faker.location.city(): For the new method that replaces this one.
    *
    * @example
    * faker.location.cityName() // 'San Rafael'
@@ -208,7 +208,7 @@ export class LocationModule {
   /**
    * Returns a random localized street name.
    *
-   * @see faker.location.street()
+   * @see faker.location.street(): For the new method that replaces this one.
    *
    * @example
    * fakerDE.location.streetName() // 'Cavill Avenue'
diff --git a/src/modules/number/index.ts b/src/modules/number/index.ts
index 9216df7a583..7a95bf77885 100644
--- a/src/modules/number/index.ts
+++ b/src/modules/number/index.ts
@@ -31,7 +31,7 @@ export class NumberModule {
    *
    * @throws When options define `max < min`.
    *
-   * @see faker.string.numeric() If you would like to generate a `string` of digits with a given length (range).
+   * @see faker.string.numeric(): If you would like to generate a `string` of digits with a given length (range).
    *
    * @example
    * faker.number.int() // 2900970162509863
@@ -172,7 +172,7 @@ export class NumberModule {
    *
    * @throws When options define `max < min`.
    *
-   * @see faker.string.binary() If you would like to generate a `binary string` with a given length (range).
+   * @see faker.string.binary(): If you would like to generate a `binary string` with a given length (range).
    *
    * @example
    * faker.number.binary() // '1'
@@ -220,7 +220,7 @@ export class NumberModule {
    *
    * @throws When options define `max < min`.
    *
-   * @see faker.string.octal() If you would like to generate an `octal string` with a given length (range).
+   * @see faker.string.octal(): If you would like to generate an `octal string` with a given length (range).
    *
    * @example
    * faker.number.octal() // '5'
diff --git a/src/modules/person/index.ts b/src/modules/person/index.ts
index f07727a2c96..8e5db04fdd7 100644
--- a/src/modules/person/index.ts
+++ b/src/modules/person/index.ts
@@ -237,7 +237,7 @@ export class PersonModule {
   /**
    * Returns a random gender.
    *
-   * @see faker.person.sex() if you would like to generate binary-gender value
+   * @see faker.person.sex(): If you would like to generate binary-gender values.
    *
    * @example
    * faker.person.gender() // 'Trans*Man'
@@ -256,7 +256,8 @@ export class PersonModule {
    * Output of this method is localised, so it should not be used to fill the parameter `sex`
    * available in some other modules for example `faker.person.firstName()`.
    *
-   * @see faker.person.gender() if you would like to generate gender related values.
+   * @see faker.person.gender(): If you would like to generate gender related values.
+   * @see faker.person.sexType(): If you would like to use the sex value as a parameter.
    *
    * @example
    * faker.person.sex() // 'female'
@@ -268,7 +269,10 @@ export class PersonModule {
   }
 
   /**
-   * Returns a random sex type.
+   * Returns a random sex type (usable in parameters).
+   *
+   * @see faker.person.gender(): If you would like to use the gender value in forms.
+   * @see faker.person.sex(): If you would like to use the sex value in forms.
    *
    * @example
    * faker.person.sexType() // Sex.Female
diff --git a/src/modules/random/index.ts b/src/modules/random/index.ts
index 7fa16f40bfe..7a1ea774ee8 100644
--- a/src/modules/random/index.ts
+++ b/src/modules/random/index.ts
@@ -23,8 +23,8 @@ export class RandomModule {
   /**
    * Returns a random word.
    *
-   * @see faker.lorem.word()
-   * @see faker.word.sample()
+   * @see faker.lorem.word(): To generate a random placeholder/unreadable word.
+   * @see faker.word.sample(): To generate a random existing word.
    *
    * @example
    * faker.random.word() // 'Seamless'
@@ -162,8 +162,8 @@ export class RandomModule {
    * @param count.min The minimum number of words. Defaults to `1`.
    * @param count.max The maximum number of words. Defaults to `3`.
    *
-   * @see faker.lorem.words()
-   * @see faker.word.words()
+   * @see faker.lorem.words(): To generate a sequence of random placeholder/unreadable words.
+   * @see faker.word.words(): To generate a sequence of random existing words.
    *
    * @example
    * faker.random.words() // 'neural'
@@ -225,7 +225,7 @@ export class RandomModule {
    * @param options.casing The casing of the characters. Defaults to `'mixed'`.
    * @param options.bannedChars An array with characters to exclude. Defaults to `[]`.
    *
-   * @see faker.string.alpha()
+   * @see faker.string.alpha(): For the new method replacing this one.
    *
    * @example
    * faker.random.alpha() // 'b'
@@ -285,7 +285,7 @@ export class RandomModule {
    * @param options.casing The casing of the characters. Defaults to `'lower'`.
    * @param options.bannedChars An array of characters and digits which should be banned in the generated string. Defaults to `[]`.
    *
-   * @see faker.string.alphanumeric()
+   * @see faker.string.alphanumeric(): For the new method replacing this one.
    *
    * @example
    * faker.random.alphaNumeric() // '2'
@@ -334,7 +334,7 @@ export class RandomModule {
    * @param options.allowLeadingZeros Whether leading zeros are allowed or not. Defaults to `true`.
    * @param options.bannedDigits An array of digits which should be banned in the generated string. Defaults to `[]`.
    *
-   * @see faker.string.numeric()
+   * @see faker.string.numeric(): For the new method replacing this one.
    *
    * @example
    * faker.random.numeric() // '2'
diff --git a/src/modules/string/index.ts b/src/modules/string/index.ts
index 8167ebeafb7..9afb2297895 100644
--- a/src/modules/string/index.ts
+++ b/src/modules/string/index.ts
@@ -349,7 +349,7 @@ export class StringModule {
    * @param options.length The number or range of characters to generate after the prefix. Defaults to `1`.
    * @param options.prefix Prefix for the generated number. Defaults to `'0b'`.
    *
-   * @see faker.number.binary() If you would like to generate a `binary number` (within a range).
+   * @see faker.number.binary(): If you would like to generate a `binary number` (within a range).
    *
    * @example
    * faker.string.binary() // '0b1'
@@ -391,7 +391,7 @@ export class StringModule {
    * @param options.length The number or range of characters to generate after the prefix. Defaults to `1`.
    * @param options.prefix Prefix for the generated number. Defaults to `'0o'`.
    *
-   * @see faker.number.octal() If you would like to generate an `octal number` (within a range).
+   * @see faker.number.octal(): If you would like to generate an `octal number` (within a range).
    *
    * @example
    * faker.string.octal() // '0o3'
@@ -534,7 +534,7 @@ export class StringModule {
    * @param options.allowLeadingZeros Whether leading zeros are allowed or not. Defaults to `true`.
    * @param options.exclude An array of digits which should be excluded in the generated string. Defaults to `[]`.
    *
-   * @see faker.number.int() If you would like to generate a `number` (within a range).
+   * @see faker.number.int(): If you would like to generate a `number` (within a range).
    *
    * @example
    * faker.string.numeric() // '2'
diff --git a/src/simple-faker.ts b/src/simple-faker.ts
index 9dae635813b..77fc5f0d1b7 100644
--- a/src/simple-faker.ts
+++ b/src/simple-faker.ts
@@ -43,7 +43,7 @@ export class SimpleFaker {
    * Defaults to `() => new Date()`.
    *
    * @see [Reproducible Results](https://fakerjs.dev/guide/usage.html#reproducible-results)
-   * @see faker.seed() for reproducible results.
+   * @see faker.seed(): If you wish to generate reproducible values.
    *
    * @example
    * faker.seed(1234);
@@ -131,7 +131,7 @@ export class SimpleFaker {
    * @returns The seed that was set.
    *
    * @see [Reproducible Results](https://fakerjs.dev/guide/usage.html#reproducible-results)
-   * @see faker.setDefaultRefDate() when generating relative dates.
+   * @see faker.setDefaultRefDate(): If you wish to generate reproducible relative dates.
    *
    * @example
    * // Consistent values for tests:
@@ -166,7 +166,7 @@ export class SimpleFaker {
    * @returns The seed array that was set.
    *
    * @see [Reproducible Results](https://fakerjs.dev/guide/usage.html#reproducible-results)
-   * @see faker.setDefaultRefDate() when generating relative dates.
+   * @see faker.setDefaultRefDate(): If you wish to generate reproducible relative dates.
    *
    * @example
    * // Consistent values for tests:
@@ -201,7 +201,7 @@ export class SimpleFaker {
    * @returns The seed that was set.
    *
    * @see [Reproducible Results](https://fakerjs.dev/guide/usage.html#reproducible-results)
-   * @see faker.setDefaultRefDate() when generating relative dates.
+   * @see faker.setDefaultRefDate(): If you wish to generate reproducible dates.
    *
    * @example
    * // Consistent values for tests (using a number):
diff --git a/test/scripts/apidoc/verify-jsdoc-tags.spec.ts b/test/scripts/apidoc/verify-jsdoc-tags.spec.ts
index 64cbcdb4ee5..7e3b9b16065 100644
--- a/test/scripts/apidoc/verify-jsdoc-tags.spec.ts
+++ b/test/scripts/apidoc/verify-jsdoc-tags.spec.ts
@@ -201,6 +201,14 @@ describe('verify JSDoc tags', () => {
                 expect(link, 'Expect method reference to contain ()').toContain(
                   ')'
                 );
+                expect(
+                  link,
+                  "Expect method reference to have a ': ' after the parenthesis"
+                ).toContain('): ');
+                expect(
+                  link,
+                  'Expect method reference to have a description sentence ending with a dot'
+                ).toMatch(/\): [A-Z].{9,}\.$/);
                 expect(allowedReferences).toContain(link.replace(/\(.*/, ''));
               }
             }

From 23218ebf75b808997e8aff68346a14ae7ed2a884 Mon Sep 17 00:00:00 2001
From: ST-DDT <ST-DDT@gmx.de>
Date: Fri, 13 Oct 2023 01:15:19 +0200
Subject: [PATCH 02/11] Apply suggestions from code review

Co-authored-by: DivisionByZero <leyla.jaehnig@gmx.de>
---
 src/definitions/finance.ts      | 2 +-
 src/definitions/phone_number.ts | 2 +-
 src/modules/datatype/index.ts   | 2 +-
 src/modules/random/index.ts     | 4 ++--
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/definitions/finance.ts b/src/definitions/finance.ts
index ecccb9370e0..c82ac6e85ba 100644
--- a/src/definitions/finance.ts
+++ b/src/definitions/finance.ts
@@ -13,7 +13,7 @@ export type FinanceDefinition = LocaleEntry<{
    * The pattern by (lowercase) issuer name used to generate credit card codes.
    * `L` will be replaced by the check bit.
    *
-   * @see faker.helpers.replaceCreditCardSymbols(): For more information about the how the pattern is used.
+   * @see faker.helpers.replaceCreditCardSymbols(): For more information about how the pattern is used.
    */
   credit_card: { [issuer: string]: string[] };
 
diff --git a/src/definitions/phone_number.ts b/src/definitions/phone_number.ts
index f321c9bda1b..c6543c85772 100644
--- a/src/definitions/phone_number.ts
+++ b/src/definitions/phone_number.ts
@@ -10,7 +10,7 @@ export type PhoneNumberDefinition = LocaleEntry<{
    * `!` will be replaced by a random digit (2-9).
    * (e.g. `!##-!##-####` -> 272-285-0453)
    *
-   * @see faker.helpers.replaceSymbolWithNumber(format): For more information about the how the patterns are used.
+   * @see faker.helpers.replaceSymbolWithNumber(format): For more information about how the patterns are used.
    */
   formats: string[];
 }>;
diff --git a/src/modules/datatype/index.ts b/src/modules/datatype/index.ts
index de6f9a9397c..c3d7c4c48cc 100644
--- a/src/modules/datatype/index.ts
+++ b/src/modules/datatype/index.ts
@@ -159,7 +159,7 @@ export class DatatypeModule {
    *    as maximum generated date. Defaults to `4102444800000`.
    *
    * @see faker.date.anytime(): For the new method when generating a random date in either the past or future.
-   * @see faker.date.between(): For the new method when generating a random date between the two dates.
+   * @see faker.date.between(): For the new method when generating a random date in between two dates.
    *
    * @example
    * faker.datatype.datetime() // '2089-04-17T18:03:24.956Z'
diff --git a/src/modules/random/index.ts b/src/modules/random/index.ts
index 7a1ea774ee8..b88ea58aca7 100644
--- a/src/modules/random/index.ts
+++ b/src/modules/random/index.ts
@@ -23,7 +23,7 @@ export class RandomModule {
   /**
    * Returns a random word.
    *
-   * @see faker.lorem.word(): To generate a random placeholder/unreadable word.
+   * @see faker.lorem.word(): To generate a random placeholder word.
    * @see faker.word.sample(): To generate a random existing word.
    *
    * @example
@@ -162,7 +162,7 @@ export class RandomModule {
    * @param count.min The minimum number of words. Defaults to `1`.
    * @param count.max The maximum number of words. Defaults to `3`.
    *
-   * @see faker.lorem.words(): To generate a sequence of random placeholder/unreadable words.
+   * @see faker.lorem.words(): To generate a sequence of random placeholder words.
    * @see faker.word.words(): To generate a sequence of random existing words.
    *
    * @example

From bc482768edcb2583c7f66ce3c11f66816feed532 Mon Sep 17 00:00:00 2001
From: ST-DDT <ST-DDT@gmx.de>
Date: Sun, 15 Oct 2023 16:12:27 +0200
Subject: [PATCH 03/11] chore: adjust jsdocs

---
 src/modules/person/index.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/modules/person/index.ts b/src/modules/person/index.ts
index 8e5db04fdd7..1bbbba7e329 100644
--- a/src/modules/person/index.ts
+++ b/src/modules/person/index.ts
@@ -269,7 +269,7 @@ export class PersonModule {
   }
 
   /**
-   * Returns a random sex type (usable in parameters).
+   * Returns a random sex type. The `SexType` is intended to be used in parameters and conditions.
    *
    * @see faker.person.gender(): If you would like to use the gender value in forms.
    * @see faker.person.sex(): If you would like to use the sex value in forms.

From 6cc12cff9cd5b53f0e516a2c5462f4cd9f94f3d0 Mon Sep 17 00:00:00 2001
From: ST-DDT <ST-DDT@gmx.de>
Date: Fri, 20 Oct 2023 11:33:01 +0200
Subject: [PATCH 04/11] chore: apply review suggestions

---
 test/scripts/apidoc/verify-jsdoc-tags.spec.ts | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/test/scripts/apidoc/verify-jsdoc-tags.spec.ts b/test/scripts/apidoc/verify-jsdoc-tags.spec.ts
index 7e3b9b16065..95106545de1 100644
--- a/test/scripts/apidoc/verify-jsdoc-tags.spec.ts
+++ b/test/scripts/apidoc/verify-jsdoc-tags.spec.ts
@@ -207,8 +207,16 @@ describe('verify JSDoc tags', () => {
                 ).toContain('): ');
                 expect(
                   link,
-                  'Expect method reference to have a description sentence ending with a dot'
-                ).toMatch(/\): [A-Z].{9,}\.$/);
+                  'Expect method reference to have a description starting with a capital letter'
+                ).toMatch(/\): [A-Z]/);
+                expect(
+                  link,
+                  'Expect method reference to have a description sentence'
+                ).toMatch(/\): .{10,}$/);
+                expect(
+                  link,
+                  'Expect method reference to have a description ending with a dot'
+                ).toMatch(/\.$/);
                 expect(allowedReferences).toContain(link.replace(/\(.*/, ''));
               }
             }

From fabaa65b65c61cc272e21ee05c10380fbd5d48ab Mon Sep 17 00:00:00 2001
From: ST-DDT <ST-DDT@gmx.de>
Date: Fri, 20 Oct 2023 11:34:37 +0200
Subject: [PATCH 05/11] chore: apply review suggestions

---
 src/modules/image/index.ts | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/src/modules/image/index.ts b/src/modules/image/index.ts
index 8403eee421b..914675311ab 100644
--- a/src/modules/image/index.ts
+++ b/src/modules/image/index.ts
@@ -508,7 +508,7 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
    * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
@@ -540,7 +540,7 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
    * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
@@ -572,7 +572,7 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
    * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
@@ -605,7 +605,7 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
    * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
@@ -636,7 +636,7 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
    * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
@@ -667,7 +667,7 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
    * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
@@ -698,7 +698,7 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
    * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
@@ -729,7 +729,7 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
    * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
@@ -760,7 +760,7 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
    * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
@@ -791,7 +791,7 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
    * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
@@ -822,7 +822,7 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
    * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
@@ -853,7 +853,7 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
    * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example
@@ -884,7 +884,7 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
+   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
    * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
    *
    * @example

From 481a1de48c221f1a51814593ea374bf305b4ce27 Mon Sep 17 00:00:00 2001
From: ST-DDT <ST-DDT@gmx.de>
Date: Thu, 26 Oct 2023 22:53:24 +0200
Subject: [PATCH 06/11] docs: rephrase see tags

---
 src/modules/image/index.ts    | 52 +++++++++++++++++------------------
 src/modules/internet/index.ts | 12 ++++----
 src/modules/number/index.ts   |  6 ++--
 src/modules/person/index.ts   |  4 +--
 src/modules/random/index.ts   |  8 +++---
 src/modules/string/index.ts   |  6 ++--
 src/simple-faker.ts           |  8 +++---
 7 files changed, 48 insertions(+), 48 deletions(-)

diff --git a/src/modules/image/index.ts b/src/modules/image/index.ts
index 914675311ab..cf10d9cb3c7 100644
--- a/src/modules/image/index.ts
+++ b/src/modules/image/index.ts
@@ -508,8 +508,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
-   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
+   * @see faker.image.url(): For generating a random image url (has fewer options, uses multiple image providers).
+   * @see faker.image.urlLoremFlickr(): For generating a random image url from LoremFlickr.
    *
    * @example
    * faker.image.abstract() // 'https://loremflickr.com/640/480/abstract'
@@ -540,8 +540,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
-   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
+   * @see faker.image.url(): For generating a random image url (has fewer options, uses multiple image providers).
+   * @see faker.image.urlLoremFlickr(): For generating a random image url from LoremFlickr.
    *
    * @example
    * faker.image.animals() // 'https://loremflickr.com/640/480/animals'
@@ -572,8 +572,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
-   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
+   * @see faker.image.url(): For generating a random image url (has fewer options, uses multiple image providers).
+   * @see faker.image.urlLoremFlickr(): For generating a random image url from LoremFlickr.
    *
    * @example
    * faker.image.business() // 'https://loremflickr.com/640/480/business'
@@ -605,8 +605,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
-   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
+   * @see faker.image.url(): For generating a random image url (has fewer options, uses multiple image providers).
+   * @see faker.image.urlLoremFlickr(): For generating a random image url from LoremFlickr.
    *
    * @example
    * faker.image.cats() // 'https://loremflickr.com/640/480/cats'
@@ -636,8 +636,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
-   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
+   * @see faker.image.url(): For generating a random image url (has fewer options, uses multiple image providers).
+   * @see faker.image.urlLoremFlickr(): For generating a random image url from LoremFlickr.
    *
    * @example
    * faker.image.city() // 'https://loremflickr.com/640/480/city'
@@ -667,8 +667,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
-   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
+   * @see faker.image.url(): For generating a random image url (has fewer options, uses multiple image providers).
+   * @see faker.image.urlLoremFlickr(): For generating a random image url from LoremFlickr.
    *
    * @example
    * faker.image.food() // 'https://loremflickr.com/640/480/food'
@@ -698,8 +698,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
-   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
+   * @see faker.image.url(): For generating a random image url (has fewer options, uses multiple image providers).
+   * @see faker.image.urlLoremFlickr(): For generating a random image url from LoremFlickr.
    *
    * @example
    * faker.image.nightlife() // 'https://loremflickr.com/640/480/nightlife'
@@ -729,8 +729,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
-   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
+   * @see faker.image.url(): For generating a random image url (has fewer options, uses multiple image providers).
+   * @see faker.image.urlLoremFlickr(): For generating a random image url from LoremFlickr.
    *
    * @example
    * faker.image.fashion() // 'https://loremflickr.com/640/480/fashion'
@@ -760,8 +760,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
-   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
+   * @see faker.image.url(): For generating a random image url (has fewer options, uses multiple image providers).
+   * @see faker.image.urlLoremFlickr(): For generating a random image url from LoremFlickr.
    *
    * @example
    * faker.image.people() // 'https://loremflickr.com/640/480/people'
@@ -791,8 +791,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
-   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
+   * @see faker.image.url(): For generating a random image url (has fewer options, uses multiple image providers).
+   * @see faker.image.urlLoremFlickr(): For generating a random image url from LoremFlickr.
    *
    * @example
    * faker.image.nature() // 'https://loremflickr.com/640/480/nature'
@@ -822,8 +822,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
-   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
+   * @see faker.image.url(): For generating a random image url (has fewer options, uses multiple image providers).
+   * @see faker.image.urlLoremFlickr(): For generating a random image url from LoremFlickr.
    *
    * @example
    * faker.image.sports() // 'https://loremflickr.com/640/480/sports'
@@ -853,8 +853,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
-   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
+   * @see faker.image.url(): For generating a random image url (has fewer options, uses multiple image providers).
+   * @see faker.image.urlLoremFlickr(): For generating a random image url from LoremFlickr.
    *
    * @example
    * faker.image.technics() // 'https://loremflickr.com/640/480/technics'
@@ -884,8 +884,8 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
-   * @see faker.image.url(): To generate a random image url (has fewer options, uses multiple image providers).
-   * @see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
+   * @see faker.image.url(): For generating a random image url (has fewer options, uses multiple image providers).
+   * @see faker.image.urlLoremFlickr(): For generating a random image url from LoremFlickr.
    *
    * @example
    * faker.image.transport() // 'https://loremflickr.com/640/480/transport'
diff --git a/src/modules/internet/index.ts b/src/modules/internet/index.ts
index 60eec35ddc8..7a8b108be7c 100644
--- a/src/modules/internet/index.ts
+++ b/src/modules/internet/index.ts
@@ -486,7 +486,7 @@ export class InternetModule {
    * @param options.firstName The optional first name to use. If not specified, a random one will be chosen.
    * @param options.lastName The optional last name to use. If not specified, a random one will be chosen.
    *
-   * @see faker.internet.displayName(): If you wish to generate a Unicode display name.
+   * @see faker.internet.displayName(): For generating a Unicode display name.
    *
    * @example
    * faker.internet.userName() // 'Nettie_Zboncak40'
@@ -521,7 +521,7 @@ export class InternetModule {
    * @param firstName The optional first name to use. If not specified, a random one will be chosen.
    * @param lastName The optional last name to use. If not specified, a random one will be chosen.
    *
-   * @see faker.internet.displayName(): If you wish to generate a Unicode display name.
+   * @see faker.internet.displayName(): For generating a Unicode display name.
    *
    * @example
    * faker.internet.userName() // 'Nettie_Zboncak40'
@@ -547,7 +547,7 @@ export class InternetModule {
    * @param options.lastName The optional last name to use. If not specified, a random one will be chosen.
    * @param legacyLastName The optional last name to use. If not specified, a random one will be chosen.
    *
-   * @see faker.internet.displayName(): If you wish to generate a Unicode display name.
+   * @see faker.internet.displayName(): For generating a Unicode display name.
    *
    * @example
    * faker.internet.userName() // 'Nettie_Zboncak40'
@@ -670,7 +670,7 @@ export class InternetModule {
    * @param options.firstName The optional first name to use. If not specified, a random one will be chosen.
    * @param options.lastName The optional last name to use. If not specified, a random one will be chosen.
    *
-   * @see faker.internet.userName(): If you wish to generate a plain ASCII username.
+   * @see faker.internet.userName(): For generating a plain ASCII username.
    *
    * @example
    * faker.internet.displayName() // 'Nettie_Zboncak40'
@@ -705,7 +705,7 @@ export class InternetModule {
    * @param firstName The optional first name to use. If not specified, a random one will be chosen.
    * @param lastName The optional last name to use. If not specified, a random one will be chosen.
    *
-   * @see faker.internet.userName(): If you wish to generate a plain ASCII username.
+   * @see faker.internet.userName(): For generating a plain ASCII username.
    *
    * @example
    * faker.internet.displayName() // 'Nettie_Zboncak40'
@@ -731,7 +731,7 @@ export class InternetModule {
    * @param options.lastName The optional last name to use. If not specified, a random one will be chosen.
    * @param legacyLastName The optional last name to use. If not specified, a random one will be chosen.
    *
-   * @see faker.internet.userName(): If you wish to generate a plain ASCII username.
+   * @see faker.internet.userName(): For generating a plain ASCII username.
    *
    * @example
    * faker.internet.displayName() // 'Nettie_Zboncak40'
diff --git a/src/modules/number/index.ts b/src/modules/number/index.ts
index 3c91e38da34..34e2691735a 100644
--- a/src/modules/number/index.ts
+++ b/src/modules/number/index.ts
@@ -31,7 +31,7 @@ export class NumberModule {
    *
    * @throws When options define `max < min`.
    *
-   * @see faker.string.numeric(): If you would like to generate a `string` of digits with a given length (range).
+   * @see faker.string.numeric(): For generating a `string` of digits with a given length (range).
    *
    * @example
    * faker.number.int() // 2900970162509863
@@ -175,7 +175,7 @@ export class NumberModule {
    *
    * @throws When options define `max < min`.
    *
-   * @see faker.string.binary(): If you would like to generate a `binary string` with a given length (range).
+   * @see faker.string.binary(): For generating a `binary string` with a given length (range).
    *
    * @example
    * faker.number.binary() // '1'
@@ -224,7 +224,7 @@ export class NumberModule {
    *
    * @throws When options define `max < min`.
    *
-   * @see faker.string.octal(): If you would like to generate an `octal string` with a given length (range).
+   * @see faker.string.octal(): For generating an `octal string` with a given length (range).
    *
    * @example
    * faker.number.octal() // '5'
diff --git a/src/modules/person/index.ts b/src/modules/person/index.ts
index 1bbbba7e329..57a2e54b5d3 100644
--- a/src/modules/person/index.ts
+++ b/src/modules/person/index.ts
@@ -237,7 +237,7 @@ export class PersonModule {
   /**
    * Returns a random gender.
    *
-   * @see faker.person.sex(): If you would like to generate binary-gender values.
+   * @see faker.person.sex(): For generating binary-gender values.
    *
    * @example
    * faker.person.gender() // 'Trans*Man'
@@ -256,7 +256,7 @@ export class PersonModule {
    * Output of this method is localised, so it should not be used to fill the parameter `sex`
    * available in some other modules for example `faker.person.firstName()`.
    *
-   * @see faker.person.gender(): If you would like to generate gender related values.
+   * @see faker.person.gender(): For generating gender related values.
    * @see faker.person.sexType(): If you would like to use the sex value as a parameter.
    *
    * @example
diff --git a/src/modules/random/index.ts b/src/modules/random/index.ts
index b88ea58aca7..d2a2efc4e9d 100644
--- a/src/modules/random/index.ts
+++ b/src/modules/random/index.ts
@@ -23,8 +23,8 @@ export class RandomModule {
   /**
    * Returns a random word.
    *
-   * @see faker.lorem.word(): To generate a random placeholder word.
-   * @see faker.word.sample(): To generate a random existing word.
+   * @see faker.lorem.word(): For generating a random placeholder word.
+   * @see faker.word.sample(): For generating a random existing word.
    *
    * @example
    * faker.random.word() // 'Seamless'
@@ -162,8 +162,8 @@ export class RandomModule {
    * @param count.min The minimum number of words. Defaults to `1`.
    * @param count.max The maximum number of words. Defaults to `3`.
    *
-   * @see faker.lorem.words(): To generate a sequence of random placeholder words.
-   * @see faker.word.words(): To generate a sequence of random existing words.
+   * @see faker.lorem.words(): For generating a sequence of random placeholder words.
+   * @see faker.word.words(): For generating a sequence of random existing words.
    *
    * @example
    * faker.random.words() // 'neural'
diff --git a/src/modules/string/index.ts b/src/modules/string/index.ts
index abc6f759d06..490c3610a60 100644
--- a/src/modules/string/index.ts
+++ b/src/modules/string/index.ts
@@ -345,7 +345,7 @@ export class StringModule {
    * @param options.length The number or range of characters to generate after the prefix. Defaults to `1`.
    * @param options.prefix Prefix for the generated number. Defaults to `'0b'`.
    *
-   * @see faker.number.binary(): If you would like to generate a `binary number` (within a range).
+   * @see faker.number.binary(): For generating a `binary number` (within a range).
    *
    * @example
    * faker.string.binary() // '0b1'
@@ -387,7 +387,7 @@ export class StringModule {
    * @param options.length The number or range of characters to generate after the prefix. Defaults to `1`.
    * @param options.prefix Prefix for the generated number. Defaults to `'0o'`.
    *
-   * @see faker.number.octal(): If you would like to generate an `octal number` (within a range).
+   * @see faker.number.octal(): For generating an `octal number` (within a range).
    *
    * @example
    * faker.string.octal() // '0o3'
@@ -530,7 +530,7 @@ export class StringModule {
    * @param options.allowLeadingZeros Whether leading zeros are allowed or not. Defaults to `true`.
    * @param options.exclude An array of digits which should be excluded in the generated string. Defaults to `[]`.
    *
-   * @see faker.number.int(): If you would like to generate a `number` (within a range).
+   * @see faker.number.int(): For generating a `number` (within a range).
    *
    * @example
    * faker.string.numeric() // '2'
diff --git a/src/simple-faker.ts b/src/simple-faker.ts
index 77fc5f0d1b7..b6fb3475bde 100644
--- a/src/simple-faker.ts
+++ b/src/simple-faker.ts
@@ -43,7 +43,7 @@ export class SimpleFaker {
    * Defaults to `() => new Date()`.
    *
    * @see [Reproducible Results](https://fakerjs.dev/guide/usage.html#reproducible-results)
-   * @see faker.seed(): If you wish to generate reproducible values.
+   * @see faker.seed(): For generating reproducible values.
    *
    * @example
    * faker.seed(1234);
@@ -131,7 +131,7 @@ export class SimpleFaker {
    * @returns The seed that was set.
    *
    * @see [Reproducible Results](https://fakerjs.dev/guide/usage.html#reproducible-results)
-   * @see faker.setDefaultRefDate(): If you wish to generate reproducible relative dates.
+   * @see faker.setDefaultRefDate(): For generating reproducible relative dates.
    *
    * @example
    * // Consistent values for tests:
@@ -166,7 +166,7 @@ export class SimpleFaker {
    * @returns The seed array that was set.
    *
    * @see [Reproducible Results](https://fakerjs.dev/guide/usage.html#reproducible-results)
-   * @see faker.setDefaultRefDate(): If you wish to generate reproducible relative dates.
+   * @see faker.setDefaultRefDate(): For generating reproducible relative dates.
    *
    * @example
    * // Consistent values for tests:
@@ -201,7 +201,7 @@ export class SimpleFaker {
    * @returns The seed that was set.
    *
    * @see [Reproducible Results](https://fakerjs.dev/guide/usage.html#reproducible-results)
-   * @see faker.setDefaultRefDate(): If you wish to generate reproducible dates.
+   * @see faker.setDefaultRefDate(): For generating reproducible dates.
    *
    * @example
    * // Consistent values for tests (using a number):

From 0333c74079f010507e01d5b0a01c12d573c2a1ea Mon Sep 17 00:00:00 2001
From: ST-DDT <ST-DDT@gmx.de>
Date: Thu, 26 Oct 2023 23:12:57 +0200
Subject: [PATCH 07/11] docs: standardize see tags

---
 src/modules/company/index.ts  |  4 ++--
 src/modules/datatype/index.ts | 20 ++++++++++----------
 src/modules/date/index.ts     | 30 +++++++++++++++---------------
 src/modules/finance/index.ts  |  4 ++--
 src/modules/helpers/index.ts  |  8 ++++----
 src/modules/internet/index.ts |  6 +++---
 src/modules/location/index.ts |  6 +++---
 src/modules/person/index.ts   | 10 +++++-----
 src/modules/random/index.ts   |  6 +++---
 9 files changed, 47 insertions(+), 47 deletions(-)

diff --git a/src/modules/company/index.ts b/src/modules/company/index.ts
index 7372cd674a5..594678febed 100644
--- a/src/modules/company/index.ts
+++ b/src/modules/company/index.ts
@@ -24,7 +24,7 @@ export class CompanyModule {
   /**
    * Returns an array with possible company name suffixes.
    *
-   * @see faker.company.name(): For a method that returns a complete company name.
+   * @see faker.company.name(): For generating a complete company name.
    *
    * @example
    * faker.company.suffixes() // [ 'Inc', 'and Sons', 'LLC', 'Group' ]
@@ -60,7 +60,7 @@ export class CompanyModule {
   /**
    * Returns a random company suffix.
    *
-   * @see faker.company.name(): For a method that returns a complete company name.
+   * @see faker.company.name(): For generating a complete company name.
    *
    * @example
    * faker.company.companySuffix() // 'and Sons'
diff --git a/src/modules/datatype/index.ts b/src/modules/datatype/index.ts
index c3d7c4c48cc..3825ee8b300 100644
--- a/src/modules/datatype/index.ts
+++ b/src/modules/datatype/index.ts
@@ -27,8 +27,8 @@ export class DatatypeModule {
    *
    * @throws When options define `max < min`.
    *
-   * @see faker.number.int(): For the new method when generating a random integer.
-   * @see faker.number.float(): For the new method when generating a random floating-point number.
+   * @see faker.number.int(): For generating a random integer in the future.
+   * @see faker.number.float(): For generating a random floating-point number in the future.
    *
    * @example
    * faker.datatype.number() // 55422
@@ -90,7 +90,7 @@ export class DatatypeModule {
    * @param options.max Upper bound for generated number. Defaults to `min + 99999`.
    * @param options.precision Precision of the generated number. Defaults to `0.01`.
    *
-   * @see faker.number.float(): For the new method when generating a random floating-point number.
+   * @see faker.number.float(): For the replacement method.
    *
    * @example
    * faker.datatype.float() // 51696.36
@@ -158,8 +158,8 @@ export class DatatypeModule {
    *    When not provided or larger than `8640000000000000`, `2100-01-01` is considered
    *    as maximum generated date. Defaults to `4102444800000`.
    *
-   * @see faker.date.anytime(): For the new method when generating a random date in either the past or future.
-   * @see faker.date.between(): For the new method when generating a random date in between two dates.
+   * @see faker.date.anytime(): For generating a random date in either the past or future.
+   * @see faker.date.between(): For generating a random date in between two dates.
    *
    * @example
    * faker.datatype.datetime() // '2089-04-17T18:03:24.956Z'
@@ -221,7 +221,7 @@ export class DatatypeModule {
    * @param options Length of the generated string or an options object. Defaults to `{}`.
    * @param options.length Length of the generated string. Max length is `2^20`. Defaults to `10`.
    *
-   * @see faker.string.sample(): For the new method when generating a random string.
+   * @see faker.string.sample(): For the replacement method.
    *
    * @example
    * faker.datatype.string() // 'Zo!.:*e>wR'
@@ -262,7 +262,7 @@ export class DatatypeModule {
   /**
    * Returns a UUID v4 ([Universally Unique Identifier](https://en.wikipedia.org/wiki/Universally_unique_identifier)).
    *
-   * @see faker.string.uuid(): For the new method when generating a random UUID.
+   * @see faker.string.uuid(): For the replacement method.
    *
    * @example
    * faker.datatype.uuid() // '4136cd0b-d90b-4af7-b485-5d1ded8db252'
@@ -339,8 +339,8 @@ export class DatatypeModule {
    * @param options.prefix Prefix for the generated number. Defaults to `'0x'`.
    * @param options.case Case of the generated number. Defaults to `'mixed'`.
    *
-   * @see faker.string.hexadecimal(): For the new method when generating a random hexadecimal string.
-   * @see faker.number.hex(): For the new method when generating a random hexadecimal number.
+   * @see faker.string.hexadecimal(): For generating a random hexadecimal string in the future.
+   * @see faker.number.hex(): For generating a random hexadecimal number in the future.
    *
    * @example
    * faker.datatype.hexadecimal() // '0xB'
@@ -470,7 +470,7 @@ export class DatatypeModule {
    *
    * @throws When options define `max < min`.
    *
-   * @see faker.number.bigInt(): For the new method when generating a random bigint.
+   * @see faker.number.bigInt(): For the replacement method.
    *
    * @example
    * faker.datatype.bigInt() // 55422n
diff --git a/src/modules/date/index.ts b/src/modules/date/index.ts
index 00283e627f9..09d9e3c4510 100644
--- a/src/modules/date/index.ts
+++ b/src/modules/date/index.ts
@@ -37,9 +37,9 @@ export class SimpleDateModule {
    * @param options The optional options object.
    * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
-   * @see faker.date.between(): For dates in a specific range.
-   * @see faker.date.past(): For dates explicitly in the past.
-   * @see faker.date.future(): For dates explicitly in the future.
+   * @see faker.date.between(): For generating dates in a specific range.
+   * @see faker.date.past(): For generating dates explicitly in the past.
+   * @see faker.date.future(): For generating dates explicitly in the future.
    *
    * @example
    * faker.date.anytime() // '2022-07-31T01:33:29.567Z'
@@ -73,7 +73,7 @@ export class SimpleDateModule {
    * @param options.years The range of years the date may be in the past. Defaults to `1`.
    * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
-   * @see faker.date.recent(): For dates in the recent past (days instead of years).
+   * @see faker.date.recent(): For generating dates in the recent past (days instead of years).
    *
    * @example
    * faker.date.past() // '2021-12-03T05:40:44.408Z'
@@ -102,7 +102,7 @@ export class SimpleDateModule {
    * @param years The range of years the date may be in the past. Defaults to `1`.
    * @param refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
-   * @see faker.date.recent(): For dates in the recent past (days instead of years).
+   * @see faker.date.recent(): For generating dates in the recent past (days instead of years).
    *
    * @example
    * faker.date.past() // '2021-12-03T05:40:44.408Z'
@@ -122,7 +122,7 @@ export class SimpleDateModule {
    * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    * @param legacyRefDate Deprecated, use `options.refDate` instead.
    *
-   * @see faker.date.recent(): For dates in the recent past (days instead of years).
+   * @see faker.date.recent(): For generating dates in the recent past (days instead of years).
    *
    * @example
    * faker.date.past() // '2021-12-03T05:40:44.408Z'
@@ -195,7 +195,7 @@ export class SimpleDateModule {
    * @param options.years The range of years the date may be in the future. Defaults to `1`.
    * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
-   * @see faker.date.soon(): For dates in the near future (days instead of years).
+   * @see faker.date.soon(): For generating dates in the near future (days instead of years).
    *
    * @example
    * faker.date.future() // '2022-11-19T05:52:49.100Z'
@@ -224,7 +224,7 @@ export class SimpleDateModule {
    * @param years The range of years the date may be in the future. Defaults to `1`.
    * @param refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
-   * @see faker.date.soon(): For dates in the near future (days instead of years).
+   * @see faker.date.soon(): For generating dates in the near future (days instead of years).
    *
    * @example
    * faker.date.future() // '2022-11-19T05:52:49.100Z'
@@ -244,7 +244,7 @@ export class SimpleDateModule {
    * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    * @param legacyRefDate Deprecated, use `options.refDate` instead.
    *
-   * @see faker.date.soon(): For dates in the near future (days instead of years).
+   * @see faker.date.soon(): For generating dates in the near future (days instead of years).
    *
    * @example
    * faker.date.future() // '2022-11-19T05:52:49.100Z'
@@ -587,7 +587,7 @@ export class SimpleDateModule {
    * @param options.days The range of days the date may be in the past. Defaults to `1`.
    * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
-   * @see faker.date.past(): For dates further back in time (years instead of days).
+   * @see faker.date.past(): For generating dates further back in time (years instead of days).
    *
    * @example
    * faker.date.recent() // '2022-02-04T02:09:35.077Z'
@@ -616,7 +616,7 @@ export class SimpleDateModule {
    * @param days The range of days the date may be in the past. Defaults to `1`.
    * @param refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
-   * @see faker.date.past(): For dates further back in time (years instead of days).
+   * @see faker.date.past(): For generating dates further back in time (years instead of days).
    *
    * @example
    * faker.date.recent() // '2022-02-04T02:09:35.077Z'
@@ -636,7 +636,7 @@ export class SimpleDateModule {
    * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    * @param legacyRefDate Deprecated, use `options.refDate` instead.
    *
-   * @see faker.date.past(): For dates further back in time (years instead of days).
+   * @see faker.date.past(): For generating dates further back in time (years instead of days).
    *
    * @example
    * faker.date.recent() // '2022-02-04T02:09:35.077Z'
@@ -704,7 +704,7 @@ export class SimpleDateModule {
    * @param options.days The range of days the date may be in the future. Defaults to `1`.
    * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
-   * @see faker.date.future(): For dates further in the future (years instead of days).
+   * @see faker.date.future(): For generating dates further in the future (years instead of days).
    *
    * @example
    * faker.date.soon() // '2022-02-05T09:55:39.216Z'
@@ -733,7 +733,7 @@ export class SimpleDateModule {
    * @param days The range of days the date may be in the future. Defaults to `1`.
    * @param refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
-   * @see faker.date.future(): For dates further in the future (years instead of days).
+   * @see faker.date.future(): For generating dates further in the future (years instead of days).
    *
    * @example
    * faker.date.soon() // '2022-02-05T09:55:39.216Z'
@@ -753,7 +753,7 @@ export class SimpleDateModule {
    * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    * @param legacyRefDate Deprecated, use `options.refDate` instead.
    *
-   * @see faker.date.future(): For dates further in the future (years instead of days).
+   * @see faker.date.future(): For generating dates further in the future (years instead of days).
    *
    * @example
    * faker.date.soon() // '2022-02-05T09:55:39.216Z'
diff --git a/src/modules/finance/index.ts b/src/modules/finance/index.ts
index 52695c59b0d..22fce76cad2 100644
--- a/src/modules/finance/index.ts
+++ b/src/modules/finance/index.ts
@@ -47,7 +47,7 @@ export class FinanceModule {
    *
    * @param length The length of the account number. Defaults to `8`.
    *
-   * @see faker.finance.accountNumber(): For the new method that replaces this one.
+   * @see faker.finance.accountNumber(): For the replacement method.
    *
    * @example
    * faker.finance.account() // 92842238
@@ -209,7 +209,7 @@ export class FinanceModule {
    * @param parens Whether to use surrounding parenthesis. Defaults to `true`.
    * @param ellipsis Whether to prefix the numbers with an ellipsis. Defaults to `true`.
    *
-   * @see faker.finance.maskedNumber(): For the new method that replaces this one.
+   * @see faker.finance.maskedNumber(): For the replacement method.
    *
    * @example
    * faker.finance.mask() // '(...9711)'
diff --git a/src/modules/helpers/index.ts b/src/modules/helpers/index.ts
index 75e39e07cf3..bbaa2f7f17b 100644
--- a/src/modules/helpers/index.ts
+++ b/src/modules/helpers/index.ts
@@ -329,7 +329,7 @@ export class SimpleHelpersModule {
    *
    * @param string The template string to parse.
    *
-   * @see faker.helpers.fromRegExp(): Generates a string matching the given regex like expressions.
+   * @see faker.helpers.fromRegExp(): For generating a string matching the given regex like expressions.
    *
    * @example
    * faker.helpers.regexpStyleStringParse() // ''
@@ -1296,7 +1296,7 @@ export class HelpersModule extends SimpleHelpersModule {
    *
    * @param pattern The pattern string that will get interpolated.
    *
-   * @see faker.helpers.mustache(): If you wish to use custom functions for resolution.
+   * @see faker.helpers.mustache(): For using custom functions to resolve templates.
    *
    * @example
    * faker.helpers.fake('{{person.lastName}}') // 'Barrows'
@@ -1348,7 +1348,7 @@ export class HelpersModule extends SimpleHelpersModule {
    *
    * @param patterns The array to select a pattern from, that will then get interpolated. Must not be empty.
    *
-   * @see faker.helpers.mustache(): If you wish to use custom functions for resolution.
+   * @see faker.helpers.mustache(): For using custom functions to resolve templates.
    *
    * @example
    * faker.helpers.fake(['A: {{person.firstName}}', 'B: {{person.lastName}}']) // 'A: Barry'
@@ -1391,7 +1391,7 @@ export class HelpersModule extends SimpleHelpersModule {
    *
    * @param pattern The pattern string that will get interpolated. If an array is passed, a random element will be picked and interpolated.
    *
-   * @see faker.helpers.mustache(): If you wish to use custom functions for resolution.
+   * @see faker.helpers.mustache(): For using custom functions to resolve templates.
    *
    * @example
    * faker.helpers.fake('{{person.lastName}}') // 'Barrows'
diff --git a/src/modules/internet/index.ts b/src/modules/internet/index.ts
index 7a8b108be7c..fda95a38831 100644
--- a/src/modules/internet/index.ts
+++ b/src/modules/internet/index.ts
@@ -486,7 +486,7 @@ export class InternetModule {
    * @param options.firstName The optional first name to use. If not specified, a random one will be chosen.
    * @param options.lastName The optional last name to use. If not specified, a random one will be chosen.
    *
-   * @see faker.internet.displayName(): For generating a Unicode display name.
+   * @see faker.internet.displayName(): For generating an Unicode display name.
    *
    * @example
    * faker.internet.userName() // 'Nettie_Zboncak40'
@@ -521,7 +521,7 @@ export class InternetModule {
    * @param firstName The optional first name to use. If not specified, a random one will be chosen.
    * @param lastName The optional last name to use. If not specified, a random one will be chosen.
    *
-   * @see faker.internet.displayName(): For generating a Unicode display name.
+   * @see faker.internet.displayName(): For generating an Unicode display name.
    *
    * @example
    * faker.internet.userName() // 'Nettie_Zboncak40'
@@ -547,7 +547,7 @@ export class InternetModule {
    * @param options.lastName The optional last name to use. If not specified, a random one will be chosen.
    * @param legacyLastName The optional last name to use. If not specified, a random one will be chosen.
    *
-   * @see faker.internet.displayName(): For generating a Unicode display name.
+   * @see faker.internet.displayName(): For generating an Unicode display name.
    *
    * @example
    * faker.internet.userName() // 'Nettie_Zboncak40'
diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts
index 5d50eb1bdd6..d4e38a56828 100644
--- a/src/modules/location/index.ts
+++ b/src/modules/location/index.ts
@@ -94,7 +94,7 @@ export class LocationModule {
    * @param options.state The abbreviation of the state to generate the zip code for.
    * If not specified, a random zip code is generated according to the locale's zip format.
    *
-   * @see faker.location.zipCode(): For the new method that replaces this one.
+   * @see faker.location.zipCode(): For the replacement method.
    *
    * @example
    * fakerEN_US.location.zipCodeByState("AK") // '99595'
@@ -150,7 +150,7 @@ export class LocationModule {
   /**
    * Returns a random city name from a list of real cities for the locale.
    *
-   * @see faker.location.city(): For the new method that replaces this one.
+   * @see faker.location.city(): For the replacement method.
    *
    * @example
    * faker.location.cityName() // 'San Rafael'
@@ -208,7 +208,7 @@ export class LocationModule {
   /**
    * Returns a random localized street name.
    *
-   * @see faker.location.street(): For the new method that replaces this one.
+   * @see faker.location.street(): For the replacement method.
    *
    * @example
    * fakerDE.location.streetName() // 'Cavill Avenue'
diff --git a/src/modules/person/index.ts b/src/modules/person/index.ts
index 57a2e54b5d3..a11b67c6c6e 100644
--- a/src/modules/person/index.ts
+++ b/src/modules/person/index.ts
@@ -237,7 +237,7 @@ export class PersonModule {
   /**
    * Returns a random gender.
    *
-   * @see faker.person.sex(): For generating binary-gender values.
+   * @see faker.person.sex(): For generating a binary-gender value.
    *
    * @example
    * faker.person.gender() // 'Trans*Man'
@@ -256,8 +256,8 @@ export class PersonModule {
    * Output of this method is localised, so it should not be used to fill the parameter `sex`
    * available in some other modules for example `faker.person.firstName()`.
    *
-   * @see faker.person.gender(): For generating gender related values.
-   * @see faker.person.sexType(): If you would like to use the sex value as a parameter.
+   * @see faker.person.gender(): For generating a gender related value.
+   * @see faker.person.sexType(): For generating a sex value to be used as a parameter.
    *
    * @example
    * faker.person.sex() // 'female'
@@ -271,8 +271,8 @@ export class PersonModule {
   /**
    * Returns a random sex type. The `SexType` is intended to be used in parameters and conditions.
    *
-   * @see faker.person.gender(): If you would like to use the gender value in forms.
-   * @see faker.person.sex(): If you would like to use the sex value in forms.
+   * @see faker.person.gender(): For generating a gender related value in forms.
+   * @see faker.person.sex(): For generating a binary-gender value in forms.
    *
    * @example
    * faker.person.sexType() // Sex.Female
diff --git a/src/modules/random/index.ts b/src/modules/random/index.ts
index d2a2efc4e9d..54e3b8af9aa 100644
--- a/src/modules/random/index.ts
+++ b/src/modules/random/index.ts
@@ -225,7 +225,7 @@ export class RandomModule {
    * @param options.casing The casing of the characters. Defaults to `'mixed'`.
    * @param options.bannedChars An array with characters to exclude. Defaults to `[]`.
    *
-   * @see faker.string.alpha(): For the new method replacing this one.
+   * @see faker.string.alpha(): For the replacement method.
    *
    * @example
    * faker.random.alpha() // 'b'
@@ -285,7 +285,7 @@ export class RandomModule {
    * @param options.casing The casing of the characters. Defaults to `'lower'`.
    * @param options.bannedChars An array of characters and digits which should be banned in the generated string. Defaults to `[]`.
    *
-   * @see faker.string.alphanumeric(): For the new method replacing this one.
+   * @see faker.string.alphanumeric(): For the replacement method.
    *
    * @example
    * faker.random.alphaNumeric() // '2'
@@ -334,7 +334,7 @@ export class RandomModule {
    * @param options.allowLeadingZeros Whether leading zeros are allowed or not. Defaults to `true`.
    * @param options.bannedDigits An array of digits which should be banned in the generated string. Defaults to `[]`.
    *
-   * @see faker.string.numeric(): For the new method replacing this one.
+   * @see faker.string.numeric(): For the replacement method.
    *
    * @example
    * faker.random.numeric() // '2'

From 4aa776565bebda2144be9be16ccb552f09786cba Mon Sep 17 00:00:00 2001
From: ST-DDT <ST-DDT@gmx.de>
Date: Thu, 26 Oct 2023 23:13:44 +0200
Subject: [PATCH 08/11] docs: standardize see tags

---
 src/faker.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/faker.ts b/src/faker.ts
index ccda9a4c135..f43b9c36259 100644
--- a/src/faker.ts
+++ b/src/faker.ts
@@ -146,7 +146,7 @@ export class Faker extends SimpleFaker {
      * 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() For more information about how the locales are merged.
+     * @see mergeLocales(): For more information about how the locales are merged.
      */
     locale: LocaleDefinition | LocaleDefinition[];
 
@@ -218,7 +218,7 @@ export class Faker extends SimpleFaker {
            * 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() For more information about how the locales are merged.
+           * @see mergeLocales(): For more information about how the locales are merged.
            */
           locale: LocaleDefinition | LocaleDefinition[];
 

From f8599d9703c9511033005261020db9df13aaebbe Mon Sep 17 00:00:00 2001
From: ST-DDT <ST-DDT@gmx.de>
Date: Thu, 26 Oct 2023 23:30:13 +0200
Subject: [PATCH 09/11] docs: standardize see tags

---
 src/modules/finance/index.ts                  | 6 +++---
 test/scripts/apidoc/verify-jsdoc-tags.spec.ts | 6 ++++--
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/src/modules/finance/index.ts b/src/modules/finance/index.ts
index 22fce76cad2..af4851186f0 100644
--- a/src/modules/finance/index.ts
+++ b/src/modules/finance/index.ts
@@ -629,9 +629,9 @@ export class FinanceModule {
    * Returns a random currency object, containing `code`, `name `and `symbol` properties.
    *
    * @see
-   * faker.finance.currencyCode(): For a method that returns specifically the currency code.
-   * faker.finance.currencyName(): For a method that returns specifically the currency name.
-   * faker.finance.currencySymbol(): For a method that returns specifically the currency symbol.
+   * faker.finance.currencyCode(): For generating specifically the currency code.
+   * faker.finance.currencyName(): For generating returns specifically the currency name.
+   * faker.finance.currencySymbol(): For generating returns specifically the currency symbol.
    *
    * @example
    * faker.finance.currency() // { code: 'USD', name: 'US Dollar', symbol: '$' }
diff --git a/test/scripts/apidoc/verify-jsdoc-tags.spec.ts b/test/scripts/apidoc/verify-jsdoc-tags.spec.ts
index 95106545de1..6178d437ff6 100644
--- a/test/scripts/apidoc/verify-jsdoc-tags.spec.ts
+++ b/test/scripts/apidoc/verify-jsdoc-tags.spec.ts
@@ -211,8 +211,10 @@ describe('verify JSDoc tags', () => {
                 ).toMatch(/\): [A-Z]/);
                 expect(
                   link,
-                  'Expect method reference to have a description sentence'
-                ).toMatch(/\): .{10,}$/);
+                  'Expect method reference to start with a standard description phrase'
+                ).toMatch(
+                  /\): (?:For generating |For more information about |For using |For the replacement method)/
+                );
                 expect(
                   link,
                   'Expect method reference to have a description ending with a dot'

From 16f5b633d82291b56694ce85f6f6e4d1731a2e0b Mon Sep 17 00:00:00 2001
From: ST-DDT <ST-DDT@gmx.de>
Date: Mon, 13 Nov 2023 14:43:55 +0100
Subject: [PATCH 10/11] chore: apply suggestions

---
 src/modules/datatype/index.ts | 8 ++++----
 src/modules/finance/index.ts  | 4 ++--
 src/modules/helpers/index.ts  | 2 +-
 src/modules/random/index.ts   | 4 ++--
 src/modules/string/index.ts   | 2 +-
 5 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/src/modules/datatype/index.ts b/src/modules/datatype/index.ts
index 73ef7a3256f..f46cfc0b80a 100644
--- a/src/modules/datatype/index.ts
+++ b/src/modules/datatype/index.ts
@@ -22,8 +22,8 @@ export class DatatypeModule extends SimpleModuleBase {
    *
    * @throws When options define `max < min`.
    *
-   * @see faker.number.int(): For generating a random integer in the future.
-   * @see faker.number.float(): For generating a random floating-point number in the future.
+   * @see faker.number.int(): For generating a random integer.
+   * @see faker.number.float(): For generating a random floating-point number.
    *
    * @example
    * faker.datatype.number() // 55422
@@ -334,8 +334,8 @@ export class DatatypeModule extends SimpleModuleBase {
    * @param options.prefix Prefix for the generated number. Defaults to `'0x'`.
    * @param options.case Case of the generated number. Defaults to `'mixed'`.
    *
-   * @see faker.string.hexadecimal(): For generating a random hexadecimal string in the future.
-   * @see faker.number.hex(): For generating a random hexadecimal number in the future.
+   * @see faker.string.hexadecimal(): For generating a random hexadecimal string.
+   * @see faker.number.hex(): For generating a random hexadecimal number.
    *
    * @example
    * faker.datatype.hexadecimal() // '0xB'
diff --git a/src/modules/finance/index.ts b/src/modules/finance/index.ts
index 93b74a6df0f..ee879be5bc5 100644
--- a/src/modules/finance/index.ts
+++ b/src/modules/finance/index.ts
@@ -614,8 +614,8 @@ export class FinanceModule extends ModuleBase {
    *
    * @see
    * faker.finance.currencyCode(): For generating specifically the currency code.
-   * faker.finance.currencyName(): For generating returns specifically the currency name.
-   * faker.finance.currencySymbol(): For generating returns specifically the currency symbol.
+   * faker.finance.currencyName(): For generating specifically the currency name.
+   * faker.finance.currencySymbol(): For generating specifically the currency symbol.
    *
    * @example
    * faker.finance.currency() // { code: 'USD', name: 'US Dollar', symbol: '$' }
diff --git a/src/modules/helpers/index.ts b/src/modules/helpers/index.ts
index b5a23e97949..c541cf74049 100644
--- a/src/modules/helpers/index.ts
+++ b/src/modules/helpers/index.ts
@@ -325,7 +325,7 @@ export class SimpleHelpersModule extends SimpleModuleBase {
    *
    * @param string The template string to parse. Defaults to `''`.
    *
-   * @see faker.helpers.fromRegExp(): For generating a string matching the given regex like expressions.
+   * @see faker.helpers.fromRegExp(): For generating a string matching the given regex-like expressions.
    *
    * @example
    * faker.helpers.regexpStyleStringParse() // ''
diff --git a/src/modules/random/index.ts b/src/modules/random/index.ts
index bac16ed1b44..a326f59e45d 100644
--- a/src/modules/random/index.ts
+++ b/src/modules/random/index.ts
@@ -19,7 +19,7 @@ export class RandomModule extends ModuleBase {
    * Returns a random word.
    *
    * @see faker.lorem.word(): For generating a random placeholder word.
-   * @see faker.word.sample(): For generating a random existing word.
+   * @see faker.word.sample(): For generating a random real word.
    *
    * @example
    * faker.random.word() // 'Seamless'
@@ -158,7 +158,7 @@ export class RandomModule extends ModuleBase {
    * @param count.max The maximum number of words. Defaults to `3`.
    *
    * @see faker.lorem.words(): For generating a sequence of random placeholder words.
-   * @see faker.word.words(): For generating a sequence of random existing words.
+   * @see faker.word.words(): For generating a sequence of random real words.
    *
    * @example
    * faker.random.words() // 'neural'
diff --git a/src/modules/string/index.ts b/src/modules/string/index.ts
index e5bd2b4a604..da4a60f284c 100644
--- a/src/modules/string/index.ts
+++ b/src/modules/string/index.ts
@@ -338,7 +338,7 @@ export class StringModule extends SimpleModuleBase {
    * @param options.length The number or range of characters to generate after the prefix. Defaults to `1`.
    * @param options.prefix Prefix for the generated number. Defaults to `'0b'`.
    *
-   * @see faker.number.binary(): For generating a `binary number` (within a range).
+   * @see faker.number.binary(): For generating a binary number (within a range).
    *
    * @example
    * faker.string.binary() // '0b1'

From f18639c4b3ade3dd8cd8e7d67c6b80b5ba54727d Mon Sep 17 00:00:00 2001
From: ST-DDT <ST-DDT@gmx.de>
Date: Mon, 13 Nov 2023 14:45:49 +0100
Subject: [PATCH 11/11] chore: apply suggestions

---
 src/modules/string/index.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/modules/string/index.ts b/src/modules/string/index.ts
index da4a60f284c..4240a6f13a5 100644
--- a/src/modules/string/index.ts
+++ b/src/modules/string/index.ts
@@ -390,7 +390,7 @@ export class StringModule extends SimpleModuleBase {
    * @param options.length The number or range of characters to generate after the prefix. Defaults to `1`.
    * @param options.prefix Prefix for the generated number. Defaults to `'0o'`.
    *
-   * @see faker.number.octal(): For generating an `octal number` (within a range).
+   * @see faker.number.octal(): For generating an octal number (within a range).
    *
    * @example
    * faker.string.octal() // '0o3'
@@ -543,7 +543,7 @@ export class StringModule extends SimpleModuleBase {
    * @param options.allowLeadingZeros Whether leading zeros are allowed or not. Defaults to `true`.
    * @param options.exclude An array of digits which should be excluded in the generated string. Defaults to `[]`.
    *
-   * @see faker.number.int(): For generating a `number` (within a range).
+   * @see faker.number.int(): For generating a number (within a range).
    *
    * @example
    * faker.string.numeric() // '2'