Incorporating now deprecated valid-jsdoc ESLint jsdoc rules and options which we do not already support

[brettz9]

If you weren't aware, ESLint has end-of-lifed their jsdoc support: https://eslint.org/blog/2018/11/jsdoc-end-of-life (and are recommending eslint-plugin-jsdoc as a replacement).

Besides this it would be very nice to incorporate the functionality of require-jsdoc and valid-jsdoc which are not part of eslint-plugin-jsdoc and document how to transition... See https://github.com/gajus/eslint-plugin-jsdoc/wiki/Comparison-with-deprecated-JSdoc-related-ESLint-rules for already existing equivalents or near-equivalents and below for the remaining.

For require-jsdoc, see #162. (original source and tests) Merged

For our need to deal with the deprecation of sourceCode.getJSDocComment, see #189. Merged

We have no equivalents yet for the following behaviors:

• - require-returns - "@constructor tag allows missing @returns tag" v4.8.1
• - require-returns - "class constructor allows missing @returns tag" v4.8.1
• - require-returns - "@override tag allows missing ... @returns tags" v4.8.1

We have no equally powerful/granular replacements for the following options:

• - matchDescription option: require-description-complete-sentence and newline-after-description can handle subsets of this, but matchDescription is more flexible and powerful.
• - Review valid-jsdoc source for any discrepancies or missing subfeatures with existing equivalent behaviors (require-jsdoc has already been reimplemented); this should also assist in closing Document how eslint-plugin-jsdoc is different from valid-jsdoc #1 ; current PRs should handle all behavior differences.
• - preferType option: check-types is only able to enforce one specific set of types, rather than arbitrary remapping of preferred types (I've suggested at How to disallow '*' type? #166 that we also allow the values to be false to indicate there is no preferred replacement--just a blanket prohibition of that type.) Update wiki mentions of preferType when done

[brettz9]

FWIW, I also had filed this issue related to improving the support they had:

• Expand matchDescription to apply when certain fields are present, and to apply to fields which are description-like : valid-jsdoc: Expand matchDescription to apply when certain fields are present, and to apply to fields which are description-like eslint/eslint#11043

[plroebuck]

Is there a mapping for whatever ESLint's jsdoc did to whatever of your plugin rules would apply?

[brettz9]

I am not aware of any, but you could take a look at the two ESLint rules which they are planning to remove and compare with the plugin's:

• https://eslint.org/docs/rules/require-jsdoc
• https://eslint.org/docs/rules/valid-jsdoc

Note that while there are only two rules, there are a good number of options for the latter.

I have been using eslint-plugin-jsdoc and these rules both in my config as each does some things the other does not.

[bary12]

Not 100% related, but maybe it will be beneficial to write a document (or a segment in the README) explaining how to transition from the built-in ESLint rules to the plugin?

[brettz9]

I've updated my original comment just now to also request documenting of this...

[ThosRTanner]

It'd be really nice to have a require-jsdoc equivalent.

[thsmi]

#162 relates to this issue

[brettz9]

I've updated this issue to focus exclusively on valid-jsdoc and implementing those aspects/options which we don't already support. Tracking for require-jsdoc as mentioned is in #162

[brettz9]

I've also moved mention of our need to replace reliance on ESLint's SourceCode#getJSDocComment over to #189.

And I've started a wiki page at https://github.com/gajus/eslint-plugin-jsdoc/wiki/Comparison-with-deprecated-JSdoc-related-ESLint-rules to try to map any existing equivalents or tracking issues for planned future equivalents for the various dimensions and options of the deprecated valid-jsdoc feature (though up to this moment, I've mostly just set up the tables and haven't listed existing equivalents yet).

[brettz9]

Ok, the wiki pages should now be complete, and I've revised my original comment in this issue to summarize the 5 capabilities remaining from ESLint which are not available at the moment in eslint-plugin-jsdoc (3 of which relate to require-returns behavior).

[brettz9]

Regarding the matchDescription regex string setting allowed by valid-jsdoc, @gajus , where would you suggest putting an equivalent? As a setting accessible to require-description-complete-sentence which would override its behavior or a new rule with an option (or with a setting)?

[gajus]

🎉 This issue has been resolved in version 6.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀