Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: consistent @see jsdoc tags #2473

Merged
merged 28 commits into from
Nov 20, 2023
Merged

Conversation

ST-DDT
Copy link
Member

@ST-DDT ST-DDT commented Oct 12, 2023

Fixes #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.

@ST-DDT ST-DDT added c: docs Improvements or additions to documentation p: 1-normal Nothing urgent labels Oct 12, 2023
@ST-DDT ST-DDT added this to the vAnytime milestone Oct 12, 2023
@ST-DDT ST-DDT requested review from a team October 12, 2023 16:12
@ST-DDT ST-DDT self-assigned this Oct 12, 2023
@codecov
Copy link

codecov bot commented Oct 12, 2023

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

src/definitions/finance.ts Outdated Show resolved Hide resolved
src/definitions/phone_number.ts Outdated Show resolved Hide resolved
src/modules/datatype/index.ts Outdated Show resolved Hide resolved
src/modules/image/index.ts Outdated Show resolved Hide resolved
src/modules/person/index.ts Outdated Show resolved Hide resolved
src/modules/random/index.ts Outdated Show resolved Hide resolved
src/modules/random/index.ts Outdated Show resolved Hide resolved
test/scripts/apidoc/verify-jsdoc-tags.spec.ts Outdated Show resolved Hide resolved
Copy link
Contributor

@matthewmayer matthewmayer left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

src/modules/image/index.ts Outdated Show resolved Hide resolved
@ST-DDT
Copy link
Member Author

ST-DDT commented Oct 20, 2023

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
Copy link
Contributor

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
Copy link
Contributor

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

@ST-DDT ST-DDT marked this pull request as draft October 22, 2023 21:26
src/modules/datatype/index.ts Outdated Show resolved Hide resolved
src/modules/datatype/index.ts Outdated Show resolved Hide resolved
src/modules/datatype/index.ts Outdated Show resolved Hide resolved
src/modules/finance/index.ts Outdated Show resolved Hide resolved
src/modules/helpers/index.ts Outdated Show resolved Hide resolved
src/modules/random/index.ts Outdated Show resolved Hide resolved
src/modules/random/index.ts Outdated Show resolved Hide resolved
src/modules/string/index.ts Outdated Show resolved Hide resolved
src/modules/string/index.ts Outdated Show resolved Hide resolved
src/modules/string/index.ts Outdated Show resolved Hide resolved
@ST-DDT ST-DDT requested review from matthewmayer and a team November 13, 2023 13:46
@xDivisionByZerox xDivisionByZerox enabled auto-merge (squash) November 20, 2023 23:22
@xDivisionByZerox xDivisionByZerox merged commit 808aa82 into next Nov 20, 2023
20 checks passed
@ST-DDT ST-DDT deleted the jsdocs/consistent-see-tags branch November 20, 2023 23:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
c: docs Improvements or additions to documentation p: 1-normal Nothing urgent
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Unify @see jsdoc tags
3 participants