Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

better support for enforcing required tags #1235

Open
wjhsf opened this issue Jun 4, 2024 · 0 comments
Open

better support for enforcing required tags #1235

wjhsf opened this issue Jun 4, 2024 · 0 comments

Comments

@wjhsf
Copy link
Contributor

wjhsf commented Jun 4, 2024

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 #936 (comment).

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']
  }
]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant