Consistent formatting of examples (return values)

[ST-DDT]

Continuation of #3287

• Add refresh button to the api docs examples #3287

---

The examples are inconsistently formatted, both in our source code and when running the refresh on the website.

• string without quotes:
  

  faker/src/modules/finance/index.ts

  Lines 126 to 128 in 00be2e1

  	* faker.finance.accountNumber() // 92842238
  	* faker.finance.accountNumber(5) // 28736
  	* faker.finance.accountNumber({ length: 5 }) // 32564

• single line string newline:
  

  faker/src/modules/finance/index.ts

  Lines 971 to 972 in 00be2e1

  	* faker.finance.transactionDescription()
  	* // 'payment transaction at Emard LLC using card ending with ****9187 for HNL 506.57 in account ***2584.'

• single line string inline:
  

  faker/src/modules/food/index.ts

  Line 43 in 3c7abb5

  * faker.food.description() // 'An exquisite ostrich roast, infused with the essence of longan, slow-roasted to bring out its natural flavors and served with a side of creamy red cabbage'

• array without leading/ending space:
  

  faker/src/modules/helpers/index.ts

  Line 821 in 3c7abb5

  * faker.helpers.objectEntry({ prop1: 'value1', prop2: 'value2' }) // ['prop1', 'value1']

• array with leading/ending space:
  

  faker/src/modules/helpers/index.ts

  Line 619 in 3c7abb5

  * faker.helpers.shuffle(['a', 'b', 'c']) // [ 'b', 'c', 'a' ]

Also some examples seem to refer to old parameter defaults or locale data as well.

We should define a function that formats our examples consistently.
Potentially automatically via script.

[ST-DDT]

Blocked by #3301

• docs(api): add refresh button to examples #3301

[ST-DDT]

What is (in your opinion) the expected formatting for:

• Objects:
  1. { 'name': 'French', 'alpha2': 'fr', 'alpha3': 'fra' }
  2. { name: 'French', alpha2: 'fr', alpha3: 'fra' }
  3. {name: 'French', alpha2: 'fr', alpha3: 'fra'}
  4. {\n name: 'French',\n alpha2: 'fr',\n alpha3: 'fra'\n}
  5. other
• Arrays:
  1. [ 'b', 'c', 'a' ]
  2. ['b', 'c', 'a']
  3. [\n 'b',\n 'c',\n 'a'\n]
  4. other

[ST-DDT]

How should it be implemented:

1. via prettier (asynchronously downloaded on demand)
2. via the current formatResult script

[ST-DDT]

When should we use a newline for long string results?

1. If the string is longer than 50/x characters
2. Never (Current, at least for our refresh logic)

Please note that we cannot take the producing code (faker.number.int()) into consideration, as that information isn't available in that context.

[matthewmayer]

I would expect similar formatting to the Node REPL

[ST-DDT]

How should we display Dates/prototype based objects?

Ref: https://github.com/faker-js/faker/pull/3348/files#diff-33d9552c7d1fb7f98cb50e15888b577d2609cd9b6f17a333b641752c5049629d

• as json
• as Date(json)
• as unquoted string
• as toString
• as other?

[ST-DDT]

I would expect similar formatting to the Node REPL

> new Date()
2024-12-28T19:10:27.442Z
> 'foobar'
'foobar'
> ['test','a']
[ 'test', 'a' ]
> { foo:'bar', 'a':1}
{ foo: 'bar', a: 1 }

Looks pretty similar to what we have already 👍