Add JSDoc
QuentinLemCode opened this issue · comments
Please avoid duplicates
- I checked all open feature requests and none of them matched my request.
Context
When using Nock, most of the functions don't have JSDoc.
It would improve the developer experience, as it would allow one to understand how to use a function directly in the IDE without having to search for the nock documentation.
Example in VSCode :
With JSDoc it would give something like that :
Of course, the JSDoc should be replicated in Typescript types.
Alternatives
No response
If the feature request is accepted, would you be willing to submit a PR?
- yes
I am not against JSDoc, i personally prefer it. But I dont know the opinion of the other maintainers.
I'm not sure this is the best option for documentation, but I see your point.
p.s: I'm using JSDoc as well for types.
Yes, the idea is not to replace the current documentation, but add some in JSDoc to improve developer experience
@QuentinLemCode how can we make sure the jsdoc and readme are updated and one of them not left behind?
@QuentinLemCode how can we make sure the jsdoc and readme are updated and one of them not left behind?
@mikicho The most obvious would be to add the rule to the contributing guideline and PR template.
If you think we need to enforce it with a CI test for example, maybe we can rework the Readme to have a structure we can reuse to generate JSDoc or inversely.
Do you have suggestions?
I haven't used jsdoc for documentation previously, so any solution that establishes a single source of truth is acceptable to me.
@mikicho
Sure, I propose to make JSDoc the single source of truth in that case. Because JSDoc is structured, it's easier to generate markdown from JSDoc than the inverse.
This project can help us achieve that : https://github.com/jsdoc2md/jsdoc-to-markdown
Another thing to take in mind is the typescript type definition file. We can use the typescript compiler to generate the type definition from JSDoc : https://www.typescriptlang.org/docs/handbook/declaration-files/dts-from-js.html
A CI build step can be added for that.
Is that all right with you?
A solution I looked for in the past is to have sections in the README wrapped HTML comment tags (e.g. somethin like <!-- jsdoc path/to/file.js#method --> ... <!-- /jsdoc -->) which could then include API specs that are defined in JS Doc. That way we would keep a high level documentation of our README, but could also include docs that live in the code, avoiding duplication. But I was not successful in the past. Maybe you know a solution that could provide that?
But even if that's not possible, I wouldn't mind adding descriptions via JSDocs, I'd just keep them short, and add a link to the README for more)