gajus / eslint-plugin-jsdoc

JSDoc specific linting rules for ESLint.
Other
1.07k stars 155 forks source link

better support for enforcing required tags #1235

Open wjhsf opened 1 month ago

wjhsf commented 1 month ago

Motivation

I want to require @see tags on my public API, to enforce links to relevant documentation. Doing so is technically possible wit the current rules, but it is not intuitive, as discussed in https://github.com/gajus/eslint-plugin-jsdoc/issues/936#issuecomment-1344614157.

Current behavior

'jsdoc/no-restricted-syntax': [
  'error',
  {
    contexts: [
      {
        comment: 'JsdocBlock:not(*:has(JsdocTag[tag=see]))',
        context: 'any',
        message: '@see required on each block',
      },
    ],
  },
]

This enforces a @see tag in each comment, but it's not intuitive. Firstly, the name of the rule is confusing - we want to enforce that there's no missing syntax, but we're using the no-restricted-syntax rule, because the no-missing-syntax rule doesn't address our use case. Secondly, configuring the rule is a tedious experience that requires digging deep into the documentation to learn about JSDoc selectors, which have a lot of scary "this is experimental" warnings.

Desired behavior

I don't want to have to dive pages deep into the documentation of an experimental feature, I just want to list my required tags and be done.

'jsdoc/required-tags': [
  'error',
  {
    tags: ['see']
  }
]