Description
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']
}
]