[chore] add require-jsdoc

[zekth]

As we want to make a robust API, we also need to have a robust documentation. Adding JsDoc check in the pipeline is necessary i think. We sometimes (me the first) forget about adding JsDoc. Then it would help for the PR review process.

I've added another eslint line for the pipeline because i don't want to flood the main one with all the warnings. Once the repo will be cleaned i think we can merge the two commands in one. Also there is some warning about _test files ignored because we don't need documentation for it. Note: only wait to disable those warns is to --quiet the eslint command.

To ignore private methods you have to do like this:
https://github.com/denoland/deno_std/compare/master...zekth:jsdo_proposal?expand=1#diff-3dabb7bf52bbca9c45474fe23c1d029bR122

For the moment only the rule of missing jsdoc is applied. Feel free to give you thoughts about adding rules.
Here is the doc: https://eslint.org/docs/rules/require-jsdoc

[ry]

All of these @Private comments are superfluous. Either the method is public and exported or it's private. How can we adding these superfluous comments?

[zekth]

Agree with you and i've not found any workaround (for now) for this problem. There is only this in the doc: https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-settings-allow-private-to-disable-rules-for-that-comment-block

Problem is this is the reference plugin from eslint : https://eslint.org/blog/2018/11/jsdoc-end-of-life and it seems a bit incomplete for the private part.

[j-f1]

Here’s the issue: gajus/eslint-plugin-jsdoc#192 and the PR: gajus/eslint-plugin-jsdoc#262

[zekth]

GREAT
i'll delete the @private so and wait for the PR to be landed

[zekth]

@ry is it still revelant to add to the CI? I've seen the PR has been merged for eslint-plugin-jsdoc. I have a local branch working with it. Do you want me to push it?

[ry]

It seems unreasonable to require jsdoc for everything. Can it be enforced for only exported functions?

[zekth]

It seems unreasonable to require jsdoc for everything. Can it be enforced for only exported functions?

Now with the merged PR it throws errors only on missing jsdoc on exported funcs. Using this argument:

    "rules": {
        "jsdoc/require-jsdoc": [
            "error",
            {
                "publicOnly": true
            }
        ]
    }

[zekth]

Closing as a new one as been created.