infra: improve error messages for parameter properties

[ST-DDT]

Partially fixes #3079

• Non-intuitive error if options property doesn't have jsdocs #3079

Adds distinct error references for option parameter's properties and outputs them to the github action errors.

[netlify]

✅ Deploy Preview for fakerjs ready!

Name	Link
🔨 Latest commit	804f735
🔍 Latest deploy log	https://app.netlify.com/sites/fakerjs/deploys/66df7c922466f90008d92282
😎 Deploy Preview	https://deploy-preview-3082.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]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.96%. Comparing base (f128d77) to head (804f735).
Report is 1 commits behind head on next.

Additional details and impacted files

@@           Coverage Diff            @@
##             next    #3082    +/-   ##
========================================
  Coverage   99.95%   99.96%            
========================================
  Files        2776     2776            
  Lines      226260   226260            
  Branches      587      939   +352     
========================================
+ Hits       226164   226185    +21     
+ Misses         96       75    -21     

see 1 file with indirect coverage changes

[ST-DDT]

I also added an error notification to the script:

[ST-DDT]

Any wishes regarding the two error message parts (mainText + causeText)?

[Shinigami92]

I would potentially still be a bit confused when I would encounter such a causeText, but I see that you just pass forward the error.message. So for now this is fine for me.

[ST-DDT]

I would potentially still be a bit confused when I would encounter such a causeText

The causeText is just defined in a different location.

faker/scripts/apidocs/utils/value-checks.ts

Line 4 in 17f570e

`Expected exactly one element for ${property}, got ${input.length}`

Would the following be easier to understand?

`Expected exactly one ${property} element, got ${input.length}`
`Expected exactly one jsdoc element, got 0`

(I have to check the other usages still)

[matthewmayer]

I think the real confusion is that it is not intuitive that you have to write the JSDocs for the option parameters twice, once at the top of the method and once directly above each option. So this is an improvement, but still not sure that a new contributor confronted with this message would know how to fix it.

[ST-DDT]

How about an error like this:

FakerApiDocsProcessingError: Failed to process property 'options.min' at src/modules/number/index.ts:48:11 : Expected exactly one jsdocs element, got 0. Please ensure that each method signature has JSDocs, and that all properties of option/object parameters are documented with both @param tags and inline JSDocs.

[Shinigami92]

How about an error like this:

FakerApiDocsProcessingError: Failed to process property 'options.min' at src/modules/number/index.ts:48:11 : Expected exactly one jsdocs element, got 0. Please ensure that each method signature has JSDocs, and that all properties of option/object parameters are documented with both @param tags and inline JSDocs.

This is BY FAR EXORBITANT much better 😍

[xDivisionByZerox]

Great work @ST-DDT 👏