-
-
Couldn't load subscription status.
- Fork 169
Comparison with deprecated JSdoc related ESLint rules
Brett Zamir edited this page Apr 19, 2023 · 38 revisions
ESLint has end-of-lifed their jsdoc support and are recommending eslint-plugin-jsdoc as a replacement: https://eslint.org/blog/2018/11/jsdoc-end-of-life
| Deprecated JSDoc component | eslint-plugin-jsdoc replacement or tracking issue |
|---|---|
| "Maintaining the Doctrine JSDoc comment parser" | |
| "The require-jsdoc rule" | require-jsdoc |
| "The valid-jsdoc rule" | See tables below; |
| "The SourceCode#getJSDocComment method" | |
| Number | Feature from valid-jsdoc rule | Replacement within eslint-plugin-jsdoc or tracking issue | Notes |
|---|---|---|---|
| 1 | "missing return tag: @return or @returns" | require-returns | |
| 2 | "missing ... return type" | require-returns-type | |
| 3 | "missing ... return description" | require-returns-description | |
| 4 | Requiring return statement upon use of @return(s) tag | require-returns-check | Behavior not in feature summary but was referenced in documentation code comment |
| 5 | "missing parameter tag: @arg, @argument, or @param" | require-param | |
| 6 | "missing parameter ... type" | require-param-type | |
| 7 | "missing parameter ... description" | require-param-description | |
| 8 | "inconsistent order of parameter names in a comment compared to the function or method" | check-param-names | |
| 9 | "Duplicate JSDoc parameter" | check-param-names | Behavior not in feature summary nor referenced in documentation code comment, but reported in source |
| 10 | "syntax error" | valid-types | |
| 11 | "Missing JSDoc for parameter" (where @param tag is present, but not a name for it) | require-param-name | Behavior not in feature summary nor referenced in documentation code comment, but reported in source |
The "correct" code comments for valid-jsdoc also mention some specific behavior pertaining to these features:
| Tag | Behavior | eslint-plugin-jsdoc equivalent or tracking issue |
|---|---|---|
@returns | "@constructor tag allows missing @returns tag" (#1 above) | require-returns (since v4.8.1) |
@returns | "class constructor allows missing @returns tag" (#1 above) | require-returns (since v4.8.1) |
@returns | "@override tag allows missing ... @returns tags" (#1 above) | require-returns (since v4.8.1) |
@returns | "@abstract tag allows @returns tag without return statement" (#4 above) | Supported automatically in require-returns-check |
@param | "@override tag allows missing @param ... tags" (#5 above) | Supported by require-param with settings.jsdoc.overrideReplacesDocs |
Finally, this large rule had a number of options we have implemented now in our own code base:
| Option | Accepted types | Replacement within eslint-plugin-jsdoc or tracking issue |
|---|---|---|
| "prefer" | object (item to replace keyed to replacement) | check-tag-names with settings.jsdoc.tagNamePreference |
| "preferType" | object (item to replace keyed to replacement) | check-types can, in conjunction with settings.jsdoc.preferredTypes, be used to arbitrarily remap to preferred types (or also forbid types); |
| "requireReturn" | boolean | require-returns |
| "requireReturnType" | boolean | require-returns-type |
| "matchDescription" | string (regular expression) | require-description-complete-sentence and tag-lines can handle subsets of this, but matchDescription, in allowing a custom regular expression, is more flexible and powerful (unless paragraph parsing is needed). Implemented as jsdoc/match-description rule (in |
| "requireParamDescription" | boolean | require-param-description |
| "requireReturnDescription" | boolean | require-returns-description |
| "requireParamType" | boolean | require-param-type |