docs: consistent @see jsdoc tags

[ST-DDT]

Fixes #2057

• Unify @see jsdoc tags #2057

Requires that all @see tags that point to faker methods follow the following pattern:

@see faker.<module>.<method>(.*): [A-Z]___.

---

All changes are in a single PR to make it easier to cross compare the individual changes.
Feedback and re-phrasing suggestions welcome.

[codecov]

Codecov Report

Merging #2473 (ce4ebbe) into next (9619567) will decrease coverage by 0.01%.
The diff coverage is 97.02%.

Additional details and impacted files

@@            Coverage Diff             @@
##             next    #2473      +/-   ##
==========================================
- Coverage   99.57%   99.57%   -0.01%     
==========================================
  Files        2805     2805              
  Lines      250088   250093       +5     
  Branches     1100     1098       -2     
==========================================
- Hits       249031   249028       -3     
- Misses       1029     1037       +8     
  Partials       28       28              

Files	Coverage Δ
src/faker.ts	89.13% <100.00%> (ø)
src/modules/company/index.ts	100.00% <100.00%> (ø)
src/modules/datatype/index.ts	100.00% <100.00%> (ø)
src/modules/date/index.ts	99.92% <100.00%> (ø)
src/modules/finance/index.ts	100.00% <100.00%> (ø)
src/modules/helpers/index.ts	98.98% <100.00%> (ø)
src/modules/image/index.ts	100.00% <100.00%> (ø)
src/modules/internet/index.ts	100.00% <100.00%> (ø)
src/modules/location/index.ts	99.20% <100.00%> (ø)
src/modules/number/index.ts	100.00% <100.00%> (ø)
... and 7 more

... and 1 file with indirect coverage changes

[matthewmayer]

There's quite a lot of inconsistency in the phrasing like:

• If you wish to generate foo
• If you would like to generate foo
• For a method that returns foo
• To generate foo

[ST-DDT]

Here are all @see tags with plain text:

`@see` Tags

@see faker.company.name(): For a method that returns a complete company name.
@see faker.date.anytime(): For the new method when generating a random date in either the past or future.
@see faker.date.between(): For dates in a specific range.
@see faker.date.between(): For the new method when generating a random date in between two dates.
@see faker.date.future(): For dates explicitly in the future.
@see faker.date.future(): For dates further in the future (years instead of days).
@see faker.date.past(): For dates explicitly in the past.
@see faker.date.past(): For dates further back in time (years instead of days).
@see faker.date.recent(): For dates in the recent past (days instead of years).
@see faker.date.soon(): For dates in the near future (days instead of years).
@see faker.finance.accountNumber(): For the new method that replaces this one.
@see faker.finance.maskedNumber(): For the new method that replaces this one.
@see faker.helpers.fromRegExp(): Generates a string matching the given regex like expressions.
@see faker.helpers.mustache(): For more information about how the phrases are generated.
@see faker.helpers.mustache(): If you wish to use custom functions for resolution.
@see faker.helpers.replaceCreditCardSymbols(): For more information about how the pattern is used.
@see faker.helpers.replaceSymbolWithNumber(format): For more information about how the patterns are used.
@see faker.helpers.replaceSymbols(): For more information about how the pattern is used.
@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.
@see faker.internet.displayName(): If you wish to generate a Unicode display name.
@see faker.internet.userName(): If you wish to generate a plain ASCII username.
@see faker.location.city(): For the new method that replaces this one.
@see faker.location.street(): For the new method that replaces this one.
@see faker.location.zipCode(): For the new method that replaces this one.
@see faker.lorem.word(): To generate a random placeholder word.
@see faker.lorem.words(): To generate a sequence of random placeholder words.
@see faker.number.bigInt(): For the new method when generating a random bigint.
@see faker.number.binary(): If you would like to generate a `binary number` (within a range).
@see faker.number.float(): For the new method when generating a random floating-point number.
@see faker.number.hex(): For the new method when generating a random hexadecimal number.
@see faker.number.int(): For the new method when generating a random integer.
@see faker.number.int(): If you would like to generate a `number` (within a range).
@see faker.number.octal(): If you would like to generate an `octal number` (within a range).
@see faker.person.gender(): If you would like to generate gender related values.
@see faker.person.gender(): If you would like to use the gender value in forms.
@see faker.person.sex(): If you would like to generate binary-gender values.
@see faker.person.sex(): If you would like to use the sex value in forms.
@see faker.person.sexType(): If you would like to use the sex value as a parameter.
@see faker.seed(): If you wish to generate reproducible values.
@see faker.setDefaultRefDate(): If you wish to generate reproducible dates.
@see faker.setDefaultRefDate(): If you wish to generate reproducible relative dates.
@see faker.string.alpha(): For the new method replacing this one.
@see faker.string.alphanumeric(): For the new method replacing this one.
@see faker.string.binary(): If you would like to generate a `binary string` with a given length (range).
@see faker.string.hexadecimal(): For the new method when generating a random hexadecimal string.
@see faker.string.numeric(): For the new method replacing this one.
@see faker.string.numeric(): If you would like to generate a `string` of digits with a given length (range).
@see faker.string.octal(): If you would like to generate an `octal string` with a given length (range).
@see faker.string.sample(): For the new method when generating a random string.
@see faker.string.uuid(): For the new method when generating a random UUID.
@see faker.word.sample(): To generate a random existing word.
@see faker.word.words(): To generate a sequence of random existing words.
@see mergeLocales() For more information about how the locales are merged.

Any suggestion on how to simplify them to a few patterns?

We probably need at least two:

• deprecated method replacements
• alternative method suggestions

[matthewmayer]

As a first step we can replace "If you would like to generate" and "If you wish to generate" and "To generate" with

"For generating"

[matthewmayer]

If its an identical replacement method (just a rename, no parameter/behavior changes) i think we could standardise on "For the replacement method"