docs: consistent @see jsdoc tags (#2473)

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 how the pattern is used.
    */
   credit_card: { [issuer: string]: string[] };
 

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[];
 

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 how the patterns are used.
    */
   formats: string[];
 }>;

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[];
 

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'

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

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'

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: '$' }

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'