infra(docs): add script to regenerate jsdoc examples #3352

ST-DDT · 2024-12-29T20:18:24Z

Continuation of #3287

Add refresh button to the api docs examples #3287

faker.seed examples are not consistent after refresh #3345

Related to #3335

Consistent formatting of examples (return values) #3335

Adds a script to re-generate all examples' results:

pnpm run generate:examples

netlify · 2024-12-29T20:18:44Z

✅ Deploy Preview for fakerjs ready!

Name	Link
🔨 Latest commit	`ced8d2d`
🔍 Latest deploy log	https://app.netlify.com/sites/fakerjs/deploys/6771ba4d3331be000888005b
😎 Deploy Preview	https://deploy-preview-3352.fakerjs.dev
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

codecov · 2024-12-29T20:20:49Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.97%. Comparing base (39f76f7) to head (ced8d2d).

Additional details and impacted files

@@            Coverage Diff             @@
##             next    #3352      +/-   ##
==========================================
- Coverage   99.97%   99.97%   -0.01%     
==========================================
  Files        2811     2811              
  Lines      217023   217023              
  Branches      941      941              
==========================================
- Hits       216972   216970       -2     
- Misses         51       53       +2

Files with missing lines	Coverage Δ
src/faker.ts	`100.00% <ø> (ø)`
src/modules/airline/index.ts	`100.00% <ø> (ø)`
src/modules/animal/index.ts	`100.00% <ø> (ø)`
src/modules/book/index.ts	`100.00% <ø> (ø)`
src/modules/color/index.ts	`100.00% <ø> (ø)`
src/modules/commerce/index.ts	`97.71% <ø> (ø)`
src/modules/company/index.ts	`100.00% <ø> (ø)`
src/modules/database/index.ts	`100.00% <ø> (ø)`
src/modules/date/index.ts	`100.00% <ø> (ø)`
src/modules/finance/index.ts	`100.00% <ø> (ø)`
... and 18 more

ST-DDT · 2024-12-29T20:21:59Z

src/modules/color/index.ts

-   * faker.color.cmyk({ format: 'binary' }) // (8-32 bits) x 4
+   * faker.color.cmyk() // [ 0.55, 0.72, 0.6, 0.55 ]
+   * faker.color.cmyk({ format: 'css' }) // 'cmyk(42%, 65%, 44%, 90%)'
+   * faker.color.cmyk({ format: 'binary' }) // '00111111011110000101000111101100 00111110110000101000111101011100 00111111010010100011110101110001 00111111000001111010111000010100'


Not sure what to do here

ST-DDT · 2024-12-29T20:26:56Z

src/modules/date/index.ts

+   * faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z' }) // [ '2025-06-27T19:34:39.059Z', '2026-01-10T21:28:14.545Z', '2027-02-25T14:04:55.663Z' ]
+   * faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z', count: 2 }) // [ '2024-03-27T14:39:48.843Z', '2025-06-13T10:59:54.311Z' ]
+   * faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z', count: { min: 2, max: 5 }}) // [ '2023-11-01T17:05:05.418Z', '2024-05-17T12:08:45.549Z', '2028-12-01T15:31:21.089Z', '2029-08-21T06:14:29.540Z' ]


The result formatting has changed from multiline to single line.
Not sure about that.

ST-DDT · 2024-12-29T20:34:44Z

src/modules/hacker/index.ts

@@ -86,8 +86,7 @@ export class HackerModule extends ModuleBase {
   * Generates a random hacker/IT phrase.
   *
   * @example
-   * faker.hacker.phrase()
-   * // 'If we override the card, we can get to the HDD feed through the back-end HDD sensor!'
+   * faker.hacker.phrase() // 'Use the online SQL firewall, then you can hack the neural monitor!'


Inline or on newline?

ST-DDT · 2024-12-29T20:36:15Z

src/modules/helpers/index.ts

@@ -881,7 +881,7 @@ export class SimpleHelpersModule extends SimpleModuleBase {
   * @param array[].value The value to pick.
   *
   * @example
-   * faker.helpers.weightedArrayElement([{ weight: 5, value: 'sunny' }, { weight: 4, value: 'rainy' }, { weight: 1, value: 'snowy' }]) // 'sunny', 50% of the time, 'rainy' 40% of the time, 'snowy' 10% of the time
+   * faker.helpers.weightedArrayElement([{ weight: 5, value: 'sunny' }, { weight: 4, value: 'rainy' }, { weight: 1, value: 'snowy' }]) // 'rainy'


Not sure about this one

ST-DDT · 2024-12-29T20:38:45Z

src/modules/helpers/index.ts

+   * faker.helpers.enumValue(Color) // 1
+   * 
   * enum Direction { North = 'North', South = 'South'}
   * faker.helpers.enumValue(Direction) // 'South'
-   *
+   * 
   * enum HttpStatus { Ok = 200, Created = 201, BadRequest = 400, Unauthorized = 401 }
-   * faker.helpers.enumValue(HttpStatus) // 200 (Ok)
+   * faker.helpers.enumValue(HttpStatus) // 400


ST-DDT · 2024-12-29T20:48:05Z

src/modules/person/index.ts

@@ -242,7 +242,7 @@ export class PersonModule extends ModuleBase {
   * @see faker.person.sex(): For generating a binary-gender value in forms.
   *
   * @example
-   * faker.person.sexType() // Sex.Female
+   * faker.person.sexType() // 'male'


src/modules/string/index.ts

ST-DDT · 2024-12-29T20:52:50Z

src/modules/system/index.ts

+   * faker.system.cron({ includeYear: true }) // '* * * * 5 *'
+   * faker.system.cron({ includeYear: false }) // '* 22 * * *'
+   * faker.system.cron({ includeNonStandard: false }) // '40 8 14 9 *'
+   * faker.system.cron({ includeNonStandard: true }) // '59 2 7 * 4'


This should probably stay as @yearly

ST-DDT · 2024-12-29T20:54:44Z

src/simple-faker.ts

   *
   * // Default behavior
   * // faker.setDefaultRefDate();
-   * faker.date.past(); // Changes based on the current date/time
+   * faker.date.past(); // '2024-03-11T20:42:37.195Z'


Keep the old value?

ST-DDT · 2024-12-29T20:55:00Z

src/simple-faker.ts

   *
   * // Use a static ref date
-   * faker.setDefaultRefDate(new Date('2020-01-01'));
-   * faker.date.past(); // Reproducible '2019-07-03T08:27:58.118Z'
+   * faker.setDefaultRefDate(new Date('2020-01-01')); // undefined


Not sure how to handle this

matthewmayer · 2024-12-30T03:02:09Z

I'm not sure that the default sample should be completely randomly chosen though.

For example, sometimes the examples are hand picked to illustrate a point. Eg when we chose an example for faker.location.language we deliberately didn't pick English as the example.

matthewmayer · 2024-12-30T03:07:42Z

src/modules/airline/index.ts

-   * faker.airline.recordLocator({ allowVisuallySimilarCharacters: true }) // 'ANZNEI'
-   * faker.airline.recordLocator({ allowNumerics: true, allowVisuallySimilarCharacters: true }) // '1Z2Z3E'
+   * faker.airline.recordLocator() // 'PTQPKR'
+   * faker.airline.recordLocator({ allowNumerics: true }) // 'FWYDTJ'


This is another example of where a purely random example is not very helpful

Allow numeric is true, but the default example doesn't include a number

matthewmayer · 2024-12-30T06:06:18Z

src/modules/helpers/index.ts

   * faker.helpers.fromRegExp(/Joh?n/) // 'Jon'
   * faker.helpers.fromRegExp(/ABC*DE/) // 'ABDE'
-   * faker.helpers.fromRegExp(/bee+p/) // 'beeeeeeeep'


Or this example. Sure beep is valid but beeeeeeep is more instructive.

ST-DDT · 2024-12-30T07:41:07Z

I'm not sure that the default sample should be completely randomly chosen though.

Should I use a manual revert for those, or hardcode the values (or the expected condition) into the script?

matthewmayer · 2024-12-30T10:27:49Z

I don't personally think we need a script which blanket generates all examples. We could maybe have a script which adds missing examples or formats existing ones only?

ST-DDT · 2024-12-30T12:08:05Z

I don't personally think we need a script which blanket generates all examples.

I also considered this.

We could maybe have a script which adds missing examples

Are you referring to the actual code or just the values?

or formats existing ones only?

We would loose type information and would have to parse the old output to format it.
Or am I overthinking this?

One of the reasons I chose generating all (on demand) is to make it more obvious if values show the expected value and not the actual value.

Such as

. is not working in faker.helpers.fromRegExp #3302

matthewmayer · 2024-12-30T14:07:59Z

If you want to see what the actual code does, we now have the refresh button for that? So I don't think this PR adds much value and we might easily remove useful examples by accident if we run it unthinkingly.

ST-DDT added 2 commits December 29, 2024 21:15

infra(docs): add script to regenerate jsdoc examples

3e73e88

docs: update all examples

5b7e38f

ST-DDT added c: docs Improvements or additions to documentation p: 1-normal Nothing urgent c: infra Changes to our infrastructure or project setup labels Dec 29, 2024

ST-DDT added this to the vAnytime milestone Dec 29, 2024

ST-DDT self-assigned this Dec 29, 2024

chore: auto format

24406d0

ST-DDT commented Dec 29, 2024

View reviewed changes

ST-DDT mentioned this pull request Dec 29, 2024

faker.seed examples are not consistent after refresh #3345

Open

ST-DDT added 2 commits December 29, 2024 22:05

chore: no html escaping for jsdocs

f902606

chore: replace nbsp with spaces

ced8d2d

matthewmayer reviewed Dec 30, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

infra(docs): add script to regenerate jsdoc examples #3352

infra(docs): add script to regenerate jsdoc examples #3352

ST-DDT commented Dec 29, 2024 •

edited

Loading

netlify bot commented Dec 29, 2024 •

edited

Loading

codecov bot commented Dec 29, 2024 •

edited

Loading

ST-DDT Dec 29, 2024

ST-DDT Dec 29, 2024

ST-DDT Dec 29, 2024

ST-DDT Dec 29, 2024

ST-DDT Dec 29, 2024

ST-DDT Dec 29, 2024

ST-DDT Dec 29, 2024

ST-DDT Dec 29, 2024

ST-DDT Dec 29, 2024

matthewmayer commented Dec 30, 2024 •

edited

Loading

matthewmayer Dec 30, 2024

matthewmayer Dec 30, 2024

ST-DDT commented Dec 30, 2024 •

edited

Loading

matthewmayer commented Dec 30, 2024

ST-DDT commented Dec 30, 2024 •

edited

Loading

matthewmayer commented Dec 30, 2024

infra(docs): add script to regenerate jsdoc examples #3352

Are you sure you want to change the base?

infra(docs): add script to regenerate jsdoc examples #3352

Conversation

ST-DDT commented Dec 29, 2024 • edited Loading

netlify bot commented Dec 29, 2024 • edited Loading

✅ Deploy Preview for fakerjs ready!

codecov bot commented Dec 29, 2024 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

matthewmayer commented Dec 30, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ST-DDT commented Dec 30, 2024 • edited Loading

matthewmayer commented Dec 30, 2024

ST-DDT commented Dec 30, 2024 • edited Loading

matthewmayer commented Dec 30, 2024

ST-DDT commented Dec 29, 2024 •

edited

Loading

netlify bot commented Dec 29, 2024 •

edited

Loading

codecov bot commented Dec 29, 2024 •

edited

Loading

matthewmayer commented Dec 30, 2024 •

edited

Loading

ST-DDT commented Dec 30, 2024 •

edited

Loading

ST-DDT commented Dec 30, 2024 •

edited

Loading