Rule to report invalid inline jsdoc tags

[ST-DDT]

Motivation

I recently discovered that one of my jsdocs was broken due to missing inline code blocks.

 * @param options.includeNonStandard Whether to include a @yearly, @monthly, @daily, etc text labels in the generated expression. Defaults to `false`.

When hovered, this shows like this in vscode:

The same behavior is visible, when viewing at the TS-AST.

Current behavior

I couldn't find a rule here that reports unknown tags or typos in tags.

Desired behavior

A new rule/options that checks which jsdoc tags exist and check them against a (possibly configurable) allowed list of tags.

Alternatives considered

I tried using

'jsdoc/require-asterisk-prefix': 'error',

but sadly that doesn't detect this kind of error either.

[brettz9]

The rule check-tag-names checks for known tag names in the block position for tags.

Where you are putting the tags, TypeScript (and thus VSCode) expect escaping; the display issue is therefore not related to invalid tag names. You can either add a backslash in front of the @ or enclose the full tag names in backticks.

If you still want to check inline tag names, indeed check-tag-names does not do so. One problem if such a rule were to be added is that one couldn't be sure they were actually intended as tag names (it could be some other use of the at sign). The original JSDoc standard expects inline tags to be surrounded with curly brackets, e.g., {@link someURL} (see, e.g., https://jsdoc.app/about-block-inline-tags#examples and https://jsdoc.app/tags-inline-link and https://jsdoc.app/tags-inline-tutorial ). We could check that this form of link is one of the recognized tags allowable inline, but otherwise, I think it gets tricky.

[ST-DDT]

Where you are putting the tags, TypeScript (and thus VSCode) expect escaping; the display issue is therefore not related to invalid tag names. You can either add a backslash in front of the @ or enclose the full tag names in backticks.

I don't want those to be jsdoc tag things, those are supposed to be code pieces that just happen to have the code blocks forgotten.

We have check-tag-names enabled and also tried require-asterisk-prefix, but it doesn't report these either.

I would like to have a way to mark these inline jsdoc tags as invalid (or needing wrapping) e.g. like this:

Does this explain my feature request better?

[brettz9]

Yes, that helps clarify. And, \@someTag would also not be reported since it is already escaped, but you want to consider @someTag as invalid if not escaped in the manners discussed.

I'm not sure we want such a rule to apply everywhere, at least if not in typescript mode, since @ may have other uses (e.g., for email addresses) and the original JSDoc standard does not insist on escaping for it, but I think it would be a helpful rule.

[ST-DDT]

a@yearly doesn't get picked up as jsdoc tag. Only if it has a leading whitespace.

[brettz9]

Ok, but there is still the likes of @nodejs for a X/Twitter handle. What I am suggesting is to apply the rule for typescript mode, the default, so it should normally be applied.

[brettz9]

Though it won't provide a fixer, you could use jsdoc/no-restricted-syntax like the following:

  'jsdoc/no-restricted-syntax': ['warn', {
    comment: 'JsdocBlock:has(JsdocDescriptionLine[description=/(?:^|\\s)@/])',
    context: 'FunctionDeclaration',
  }]