docs: add @since tags to all methods

[matthewmayer]

Following on from discussion in #1241 i added @since jsdoc tags to all existing public methods, and exposed this in the documentation:

This is a one-off large diff for this initial integration, in future it would just be necessary to add @since tags for any newly added methods.

[ST-DDT]

I think I like this.

Please also add a new test case to: https://github.com/faker-js/faker/blob/main/test/scripts/apidoc/signature.example.ts

Also not sure whether there should be an empty line after the @examples and before @since.

[xDivisionByZerox]

Also not sure whether there should be an empty line after the @examples and before @since.

There definitely should be IMO. Looks a lot better with all topics grouped. Much easier to scan (as a human) as well.

[xDivisionByZerox]

Please add spaces around the @since tag so it aligns with the other tags.

[matthewmayer]

I think I like this.

Please also add a new test case to: https://github.com/faker-js/faker/blob/main/test/scripts/apidoc/signature.example.ts

Also not sure whether there should be an empty line after the @examples and before @since.

Sorry my typescript is not really up to this. Maybe someone else can help me with the tests

[matthewmayer]

added the newlines and made the other suggested changes.

[ST-DDT]

I will address the test later today.

[Shinigami92]

Really cool 👍
Count me as approved when all the missing requested/required tasks are finished

[codecov]

Codecov Report

Merging #1337 (3235c75) into main (508082c) will increase coverage by 0.00%.
The diff coverage is 100.00%.

❗ Current head 3235c75 differs from pull request most recent head 5fbc511. Consider uploading reports for the commit 5fbc511 to get more accurate results

@@           Coverage Diff            @@
##             main    #1337    +/-   ##
========================================
  Coverage   99.63%   99.63%            
========================================
  Files        2163     2163            
  Lines      240701   241242   +541     
  Branches     1017     1018     +1     
========================================
+ Hits       239817   240359   +542     
+ Misses        863      862     -1     
  Partials       21       21            

Impacted Files	Coverage Δ
src/modules/address/index.ts	99.82% <100.00%> (+0.01%)	⬆️
src/modules/animal/index.ts	100.00% <100.00%> (ø)
src/modules/color/index.ts	99.73% <100.00%> (+0.02%)	⬆️
src/modules/commerce/index.ts	100.00% <100.00%> (ø)
src/modules/company/index.ts	100.00% <100.00%> (ø)
src/modules/database/index.ts	100.00% <100.00%> (ø)
src/modules/datatype/index.ts	96.24% <100.00%> (+0.21%)	⬆️
src/modules/date/index.ts	99.10% <100.00%> (+0.05%)	⬆️
src/modules/fake/index.ts	100.00% <100.00%> (ø)
src/modules/finance/index.ts	100.00% <100.00%> (+0.23%)	⬆️
... and 17 more

[ST-DDT]

faker.fake and faker.unique are missing the @since tags.
The @since tags won't be picked up for the color module.
I'm not sure why.

[ST-DDT]

The color methods have multiple signatures. You have to add the @since either the last one (with jsdocs) or all of them.

[matthewmayer]

In general it seems its only reading the JSDoc for the last version of a method with multiple signatures like faker.color.rgb()? So in general should the since tag be only added to the last one, or all of them?

[ST-DDT]

I think the last one is enough.

[Shinigami92]

Depends on whether you want to show this to the user who is currently using faker in an IDE or if you only want to annotate this data to generate better fakerjs.dev docs.

If first, then you need to add it to all JSDocs

[Shinigami92]

Current test results in CI:

[matthewmayer]

i agree maybe all is better. will manually fix the ones in color

[matthewmayer]

@Shinigami92 how can i run those tests locally to make sure I caught everything?

[Shinigami92]

@Shinigami92 how can i run those tests locally to make sure I caught everything?

As easy as: pnpm run test 👀

[matthewmayer]

thanks, tests now run green

[matthewmayer]

fixed those two issues