Skip to content

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

JSDoc features deprecated by ESLint

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)

Equivalents for valid-jsdoc features

INCOMPLETE

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:

@returns:

  • "@constructor tag allows missing @returns tag" (#1 above)
  • "class constructor allows missing @returns tag" (#1 above)
  • "@override tag allows missing ... @returns tags" (#1 above)
  • "@abstract tag allows @returns tag without return statement" (#4 above) - Supported automatically in require-returns-check

@param tag:

Finally, this large rule had a number of options we ought to reimplement:

INCOMPLETE

Option Accepted types Replacement within eslint-plugin-jsdoc or tracking issue
"prefer" object (item to replace keyed to replacement) 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
Clone this wiki locally