Add JSDoc about nock HOT 8 OPEN

I am not against JSDoc, i personally prefer it. But I dont know the opinion of the other maintainers.

from nock.

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.

from nock.

Yes, the idea is not to replace the current documentation, but add some in JSDoc to improve developer experience

from nock.

@QuentinLemCode how can we make sure the jsdoc and readme are updated and one of them not left behind?

from nock.

@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?

from nock.

I haven't used jsdoc for documentation previously, so any solution that establishes a single source of truth is acceptable to me.

from nock.

@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?

from nock.

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)

from nock.