New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add JSDoc #2739
Comments
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. |
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? |
@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 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 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 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) |
Please avoid duplicates
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?
The text was updated successfully, but these errors were encountered: