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 |