Exempt certain methods from `require-jsdoc`

[lozog]

Is it possible to exempt certain methods from require-jsdoc? For example, when using a framework like React, a JSDoc doesn't add anything useful on lifecycle methods.

[HsuTing]

I found a solution:

module.exports = {
  settings: {
    jsdoc: {
      additionalTagNames: {
        customTags: ['react']
      },
    },
  },
  rules: {
    'jsdoc/require-example': ['error', { exemptedBy: ['react'] }], 
    'jsdoc/require-param': ['error', { exemptedBy: ['react'] }],
    'jsdoc/require-returns': ['error', { exemptedBy: ['react'] }],
  },
};

In my component:

class Example extends React.PureComponent {
  /** @react */
  componentDidMount() { ... }

  /** @react */
  render() { ... }
}

By this way, we can ignore the jsdoc in react life cycle.
If we can use the more better way to do this, let me know, please.

[brettz9]

I think an ideal solution would be to add an exemptedContexts option. Then the user could add AST like MethodDefinition[key.name='componentDidMount'] to an array where the rule would not be enforced.

This could then be implemented by adding a :not() query to the end of the rule selector (e.g., in places where the boolean contextDefaults is currently applied; we might also expand exemptedBy (which would probably be better named to exemptedTags) to these other rules as well).

[brettz9]

I realized we can actually already exclude require-jsdoc by using negated contexts.

{
  contexts: ['MethodDefinition:not([key.name="componentDidMount"]):not([key.name="render"])']
}

Don't include {MethodDefinition: true} on the require options object though as the above will replace that.

I've added the above example to the docs.

See also the new section on "AST and Selectors" toward gaining a better understanding of how the AST for a language feature can be determined.

[nfantone]

For anyone looking to exclude jsdoc/require-jsdoc from functional components, you can use:

  "rules": {
    "jsdoc/require-jsdoc": [
      "warn",
      {
        "require": {
          "ArrowFunctionExpression": false,
          "FunctionDeclaration": false
        },
        "contexts": [
          "FunctionDeclaration:has(BlockStatement > ReturnStatement:not([argument.type='JSXElement']))",
          "ArrowFunctionExpression:has(BlockStatement > ReturnStatement:not([argument.type='JSXElement']))"
        ]
      }
    ]
  }

EDIT: Seems like my above solution has some problems when multiple ReturnStatement blocks are present within a function. I have resorted to a simpler approach, which ignores docs on functions that begin with a capital letter:

  "rules": {
    "jsdoc/require-jsdoc": [
      "warn",
      {
        "require": {
          "ArrowFunctionExpression": true,
          "FunctionDeclaration": false
        },
        "contexts": [
          "FunctionDeclaration:not([id.name=/^[A-Z].+/])"
        ]
      }
    ]
  },

[FTWinston]

Many thanks for the above! I came up with the following to disable the require-param rule for function components, whether declared as functions or arrow functions:

"rules": {
  "jsdoc/require-param": [
    "warn",
    {
      "contexts": [
        "FunctionDeclaration:not([id.name=/^[A-Z].+/])",
        "VariableDeclarator:not([id.name=/^[A-Z].+/]) > ArrowFunctionExpression"
      ]
    }
  ]
},