Skip to content
New issue

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

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

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

No branches or pull requests

1 participant