Equivalent for the require-jsdoc eslint rule set

[vpmedia]

Motivation

Report every missing piece of jsdoc comment(s).

Current behavior

Missing class and method comments are not reported as missing.

Desired behavior

Show warning for all missing jsdoc comments.

Alternatives considered

If I use the following (deprecated) eslint rule set I get warnings for missing class and method declarations:

    "require-jsdoc": ["warn", {
      "require": {
          "FunctionDeclaration": true,
          "MethodDefinition": true,
          "ClassDeclaration": true,
          "ArrowFunctionExpression": true,
          "FunctionExpression": true
      }
    }],

[vpmedia]

Sorry, "jsdoc/require-description": ["warn", {"contexts":["any"]}] does what I've described.

[vpmedia]

Re-opened, I can't configure the plugin to report missing class method jsdoc comments.

I've tried:

"settings": {
    "jsdoc": {
      "contexts": ["any"]
    }
  },

[brettz9]

"any" is a special word which we didn't allow in the case of require-jsdoc (other rules are safer as they only look for existing JSDoc blocks). While you could technically use "*" instead with global contexts, it would surely be too broad to require, as it would ask for AST everywhere:

      /**
       *
       */
      class /** */ A /** */ {
        /**
         *
         */
        method () /** */ {}
      }

To blacklist items in this case so as to narrow it down, you could use: '*:not(ClassBody, Identifier, BlockStatement)', but other contexts are likely to creep up where you don't want them. A whitelist might avoid unpleasant expectations of JSDoc blocks everywhere. In either case, you can experiment with https://astexplorer.net/ to see what AST is built for what constructs to ensure it has it where you actually want it.

[vpmedia]

@brettz9 Thanks, I will experiment with the AST Explorer. It seems the plugin is working as designed so I close the ticket. Anyway I would expect the require-jsdoc rule to include class methods as well by default in the recommended preset, but leave the decision to you. Thank you!

[brettz9]

You can use require with this rule too, with the most common ones available without contexts:

require: {
  ArrowFunctionExpression: true
  ClassDeclaration: true
  ClassExpression: true
  FunctionDeclaration: true
  FunctionExpression: true
  MethodDefinition: true
}

Arrow functions and function expressions alone might be too frequent, e.g., within array extra methods, to be useful to enable. One can also use a combination. I use the following as part of contexts:

        'Program > VariableDeclaration > ' +
          'VariableDeclarator > ArrowFunctionExpression',
        'Program > VariableDeclaration > ' +
          'VariableDeclarator > FunctionExpression',
        'ExportNamedDeclaration > VariableDeclaration > ' +
          'VariableDeclarator > ArrowFunctionExpression',
        'ExportNamedDeclaration > VariableDeclaration > ' +
          'VariableDeclarator > FunctionExpression',
        'ExportDefaultDeclaration > ArrowFunctionExpression',
        'ExportDefaultDeclaration > FunctionExpression',

        'ClassDeclaration',
        'ClassExpression',
        'FunctionDeclaration', // Default is true
        'MethodDefinition'

Besides requiring for regular functions, classes, and methods, it also finds function expressions, but only at the top level, e.g.:

export const func = () => {};

or

const func = function () {};

[brettz9]

Btw, for the other equivalents, e.g., valid-jsdoc, you can see https://github.com/gajus/eslint-plugin-jsdoc/wiki/Comparison-with-deprecated-JSdoc-related-ESLint-rules

[vpmedia]

@brettz9 Thank you, this is really helpful!