docs: consistent @see jsdoc tags (#2473)

12 files changed, 92 insertions, 87 deletions

diff --git a/src/modules/company/index.ts b/src/modules/company/index.ts
index 14fe0eba..e0f79e62 100644
--- a/src/modules/company/index.ts
+++ b/src/modules/company/index.ts
@@ -19,7 +19,7 @@ export class CompanyModule extends ModuleBase {
   /**
    * Returns an array with possible company name suffixes.
    *
-   * @see faker.company.name()
+   * @see faker.company.name(): For generating a complete company name.
    *
    * @example
    * faker.company.suffixes() // [ 'Inc', 'and Sons', 'LLC', 'Group' ]
@@ -55,7 +55,7 @@ export class CompanyModule extends ModuleBase {
   /**
    * Returns a random company suffix.
    *
-   * @see faker.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 ad0b5489..f46cfc0b 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 the default precision of `1`
-   * @see faker.number.float() for a custom precision
+   * @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
@@ -85,7 +85,7 @@ export class DatatypeModule extends SimpleModuleBase {
    * @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 replacement method.
    *
    * @example
    * faker.datatype.float() // 51696.36
@@ -153,8 +153,8 @@ export class DatatypeModule extends SimpleModuleBase {
    *    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 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'
@@ -216,7 +216,7 @@ export class DatatypeModule extends SimpleModuleBase {
    * @param options Length of the generated string or an options object.
    * @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 replacement method.
    *
    * @example
    * faker.datatype.string() // 'Zo!.:*e>wR'
@@ -257,7 +257,7 @@ export class DatatypeModule extends SimpleModuleBase {
   /**
    * 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 replacement method.
    *
    * @example
    * faker.datatype.uuid() // '4136cd0b-d90b-4af7-b485-5d1ded8db252'
@@ -334,7 +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()
+   * @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'
@@ -464,7 +465,7 @@ export class DatatypeModule extends SimpleModuleBase {
    *
    * @throws When options define `max < min`.
    *
-   * @see faker.number.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 39c85735..9b96e704 100644
--- a/src/modules/date/index.ts
+++ b/src/modules/date/index.ts
@@ -38,9 +38,9 @@ export class SimpleDateModule extends SimpleModuleBase {
    * @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'
@@ -74,7 +74,7 @@ export class SimpleDateModule extends SimpleModuleBase {
    * @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 generating dates in the recent past (days instead of years).
    *
    * @example
    * faker.date.past() // '2021-12-03T05:40:44.408Z'
@@ -103,7 +103,7 @@ export class SimpleDateModule extends SimpleModuleBase {
    * @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 generating dates in the recent past (days instead of years).
    *
    * @example
    * faker.date.past() // '2021-12-03T05:40:44.408Z'
@@ -123,7 +123,7 @@ export class SimpleDateModule extends SimpleModuleBase {
    * @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 generating dates in the recent past (days instead of years).
    *
    * @example
    * faker.date.past() // '2021-12-03T05:40:44.408Z'
@@ -196,7 +196,7 @@ export class SimpleDateModule extends SimpleModuleBase {
    * @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 generating dates in the near future (days instead of years).
    *
    * @example
    * faker.date.future() // '2022-11-19T05:52:49.100Z'
@@ -225,7 +225,7 @@ export class SimpleDateModule extends SimpleModuleBase {
    * @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 generating dates in the near future (days instead of years).
    *
    * @example
    * faker.date.future() // '2022-11-19T05:52:49.100Z'
@@ -245,7 +245,7 @@ export class SimpleDateModule extends SimpleModuleBase {
    * @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 generating dates in the near future (days instead of years).
    *
    * @example
    * faker.date.future() // '2022-11-19T05:52:49.100Z'
@@ -590,7 +590,7 @@ export class SimpleDateModule extends SimpleModuleBase {
    * @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 generating dates further back in time (years instead of days).
    *
    * @example
    * faker.date.recent() // '2022-02-04T02:09:35.077Z'
@@ -619,7 +619,7 @@ export class SimpleDateModule extends SimpleModuleBase {
    * @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 generating dates further back in time (years instead of days).
    *
    * @example
    * faker.date.recent() // '2022-02-04T02:09:35.077Z'
@@ -639,7 +639,7 @@ export class SimpleDateModule extends SimpleModuleBase {
    * @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 generating dates further back in time (years instead of days).
    *
    * @example
    * faker.date.recent() // '2022-02-04T02:09:35.077Z'
@@ -707,7 +707,7 @@ export class SimpleDateModule extends SimpleModuleBase {
    * @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 generating dates further in the future (years instead of days).
    *
    * @example
    * faker.date.soon() // '2022-02-05T09:55:39.216Z'
@@ -736,7 +736,7 @@ export class SimpleDateModule extends SimpleModuleBase {
    * @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 generating dates further in the future (years instead of days).
    *
    * @example
    * faker.date.soon() // '2022-02-05T09:55:39.216Z'
@@ -756,7 +756,7 @@ export class SimpleDateModule extends SimpleModuleBase {
    * @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 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 33db26f0..576ca0db 100644
--- a/src/modules/finance/index.ts
+++ b/src/modules/finance/index.ts
@@ -58,7 +58,7 @@ export class FinanceModule extends ModuleBase {
    *
    * @param length The length of the account number. Defaults to `8`.
    *
-   * @see faker.finance.accountNumber()
+   * @see faker.finance.accountNumber(): For the replacement method.
    *
    * @example
    * faker.finance.account() // 92842238
@@ -220,7 +220,7 @@ export class FinanceModule extends ModuleBase {
    * @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 replacement method.
    *
    * @example
    * faker.finance.mask() // '(...9711)'
@@ -629,9 +629,9 @@ export class FinanceModule extends ModuleBase {
    * 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 generating specifically the currency code.
+   * 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 667f3a51..3f121a41 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()
+   * @see faker.helpers.fromRegExp(): For generating a string matching the given regex-like expressions.
    *
    * @example
    * faker.helpers.regexpStyleStringParse() // ''
@@ -1292,7 +1292,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(): For using custom functions to resolve templates.
    *
    * @example
    * faker.helpers.fake('{{person.lastName}}') // 'Barrows'
@@ -1344,7 +1344,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(): For using custom functions to resolve templates.
    *
    * @example
    * faker.helpers.fake(['A: {{person.firstName}}', 'B: {{person.lastName}}']) // 'A: Barry'
@@ -1387,7 +1387,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(): For using custom functions to resolve templates.
    *
    * @example
    * faker.helpers.fake('{{person.lastName}}') // 'Barrows'
diff --git a/src/modules/image/index.ts b/src/modules/image/index.ts
index f5f24711..f2c3c9d0 100644
--- a/src/modules/image/index.ts
+++ b/src/modules/image/index.ts
@@ -507,8 +507,8 @@ export class ImageModule extends ModuleBase {
    * @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(): 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'
@@ -539,8 +539,8 @@ export class ImageModule extends ModuleBase {
    * @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(): 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'
@@ -571,8 +571,8 @@ export class ImageModule extends ModuleBase {
    * @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(): 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'
@@ -604,8 +604,8 @@ export class ImageModule extends ModuleBase {
    * @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(): 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'
@@ -635,8 +635,8 @@ export class ImageModule extends ModuleBase {
    * @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(): 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'
@@ -666,8 +666,8 @@ export class ImageModule extends ModuleBase {
    * @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(): 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'
@@ -697,8 +697,8 @@ export class ImageModule extends ModuleBase {
    * @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(): 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'
@@ -728,8 +728,8 @@ export class ImageModule extends ModuleBase {
    * @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(): 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'
@@ -759,8 +759,8 @@ export class ImageModule extends ModuleBase {
    * @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(): 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'
@@ -790,8 +790,8 @@ export class ImageModule extends ModuleBase {
    * @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(): 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'
@@ -821,8 +821,8 @@ export class ImageModule extends ModuleBase {
    * @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(): 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'
@@ -852,8 +852,8 @@ export class ImageModule extends ModuleBase {
    * @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(): 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'
@@ -883,8 +883,8 @@ export class ImageModule extends ModuleBase {
    * @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(): 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 bdc84dd6..8367825f 100644
--- a/src/modules/internet/index.ts
+++ b/src/modules/internet/index.ts
@@ -493,7 +493,7 @@ export class InternetModule extends ModuleBase {
    * @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(): For generating an Unicode display name.
    *
    * @example
    * faker.internet.userName() // 'Nettie_Zboncak40'
@@ -530,7 +530,7 @@ export class InternetModule extends ModuleBase {
    * @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(): For generating an Unicode display name.
    *
    * @example
    * faker.internet.userName() // 'Nettie_Zboncak40'
@@ -558,7 +558,7 @@ export class InternetModule extends ModuleBase {
    * @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(): For generating an Unicode display name.
    *
    * @example
    * faker.internet.userName() // 'Nettie_Zboncak40'
@@ -685,7 +685,7 @@ export class InternetModule extends ModuleBase {
    * @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(): For generating a plain ASCII username.
    *
    * @example
    * faker.internet.displayName() // 'Nettie_Zboncak40'
@@ -720,7 +720,7 @@ export class InternetModule extends ModuleBase {
    * @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(): For generating a plain ASCII username.
    *
    * @example
    * faker.internet.displayName() // 'Nettie_Zboncak40'
@@ -746,7 +746,7 @@ export class InternetModule extends ModuleBase {
    * @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(): For generating 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 1c20d713..e7bde32e 100644
--- a/src/modules/location/index.ts
+++ b/src/modules/location/index.ts
@@ -25,7 +25,7 @@ export class LocationModule extends ModuleBase {
    * 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'
@@ -89,7 +89,7 @@ export class LocationModule extends ModuleBase {
    * @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 replacement method.
    *
    * @example
    * fakerEN_US.location.zipCodeByState("AK") // '99595'
@@ -145,7 +145,7 @@ export class LocationModule extends ModuleBase {
   /**
    * Returns a random city name from a list of real cities for the locale.
    *
-   * @see faker.location.city()
+   * @see faker.location.city(): For the replacement method.
    *
    * @example
    * faker.location.cityName() // 'San Rafael'
@@ -203,7 +203,7 @@ export class LocationModule extends ModuleBase {
   /**
    * Returns a random localized street name.
    *
-   * @see faker.location.street()
+   * @see faker.location.street(): For the replacement method.
    *
    * @example
    * fakerDE.location.streetName() // 'Cavill Avenue'
diff --git a/src/modules/number/index.ts b/src/modules/number/index.ts
index de32af25..a20a0040 100644
--- a/src/modules/number/index.ts
+++ b/src/modules/number/index.ts
@@ -26,7 +26,7 @@ export class NumberModule extends SimpleModuleBase {
    *
    * @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
@@ -170,7 +170,7 @@ export class NumberModule extends SimpleModuleBase {
    *
    * @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'
@@ -219,7 +219,7 @@ export class NumberModule extends SimpleModuleBase {
    *
    * @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 0c5f79c3..6c5a42df 100644
--- a/src/modules/person/index.ts
+++ b/src/modules/person/index.ts
@@ -261,7 +261,7 @@ export class PersonModule extends ModuleBase {
   /**
    * Returns a random gender.
    *
-   * @see faker.person.sex() if you would like to generate binary-gender value
+   * @see faker.person.sex(): For generating a binary-gender value.
    *
    * @example
    * faker.person.gender() // 'Trans*Man'
@@ -280,7 +280,8 @@ export class PersonModule extends ModuleBase {
    * 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 a gender related value.
+   * @see faker.person.sexType(): For generating a sex value to be used as a parameter.
    *
    * @example
    * faker.person.sex() // 'female'
@@ -292,7 +293,10 @@ export class PersonModule extends ModuleBase {
   }
 
   /**
-   * Returns a random sex type.
+   * Returns a random sex type. The `SexType` is intended to be used in parameters and conditions.
+   *
+   * @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 474e8ca6..371c810e 100644
--- a/src/modules/random/index.ts
+++ b/src/modules/random/index.ts
@@ -18,8 +18,8 @@ export class RandomModule extends ModuleBase {
   /**
    * Returns a random word.
    *
-   * @see faker.lorem.word()
-   * @see faker.word.sample()
+   * @see faker.lorem.word(): For generating a random placeholder word.
+   * @see faker.word.sample(): For generating a random real word.
    *
    * @example
    * faker.random.word() // 'Seamless'
@@ -157,8 +157,8 @@ export class RandomModule extends ModuleBase {
    * @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(): For generating a sequence of random placeholder words.
+   * @see faker.word.words(): For generating a sequence of random real words.
    *
    * @example
    * faker.random.words() // 'neural'
@@ -220,7 +220,7 @@ export class RandomModule extends ModuleBase {
    * @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 replacement method.
    *
    * @example
    * faker.random.alpha() // 'b'
@@ -280,7 +280,7 @@ export class RandomModule extends ModuleBase {
    * @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 replacement method.
    *
    * @example
    * faker.random.alphaNumeric() // '2'
@@ -329,7 +329,7 @@ export class RandomModule extends ModuleBase {
    * @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 replacement method.
    *
    * @example
    * faker.random.numeric() // '2'
diff --git a/src/modules/string/index.ts b/src/modules/string/index.ts
index e841e29d..4240a6f1 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() 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'
@@ -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() 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'
@@ -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() 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'