-
-
Notifications
You must be signed in to change notification settings - Fork 159
Comparison with deprecated JSdoc related ESLint rules
Brett Zamir edited this page Apr 7, 2019
·
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" | jsdoctypeparser |
| "The require-jsdoc rule" | #162 |
| "The valid-jsdoc rule" | #107; see also tables below |
| "The SourceCode#getJSDocComment method" | #189 (not a replacement, but we must reimplement) |
| 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 | "syntax error" | valid-types |
We should examine source to see other implications |
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) |
|
@returns |
"class constructor allows missing @returns tag" (#1 above) |
|
@returns |
"@override tag allows missing ... @returns tags" (#1 above) |
|
@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.allowOverrideWithoutParam
|
Finally, this large rule had a number of options we ought to reimplement:
| 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 is only able to enforce one specific set of types, rather than arbitrary remapping of preferred types |
| "requireReturn" | boolean | require-returns |
| "requireReturnType" | boolean | require-returns-type |
| "matchDescription" | string (regular expression) |
require-description-complete-sentence and newline-after-description can handle subsets of this, but matchDescription is more flexible and powerful. |
| "requireParamDescription" | boolean | require-param-description |
| "requireReturnDescription" | boolean | require-returns-description |
| "requireParamType" | boolean | require-param-type |