New rule: disallow combining multiple `@typedef` / `@callback` tags in one comment

[remcohaszing]

Motivation

With TypeScript types in JSDoc, it’s possible to combine multiple @typedef or @callback tags. In some cases however, this causes weird hard to debug conflicts. This is demonstrated in this TypeScript playground.

Current behavior

There is no rule.

Desired behavior

It would be good if there’s a rule that disallows combining multiple @callback or @typedef tags in one JSDoc block.

Alternatives considered

At first it seemed like a good idea to have a more configurable rule to disallow duplicate tags. However, the combination of @callback and @typedef is also problematic.

[brettz9]

Try something like this:

  'jsdoc/no-restricted-syntax': ['error', {
    contexts: [
      {
        comment: 'JsdocBlock:has(JsdocTag[tag=typedef]):has(JsdocTag[tag=callback])',
        context: 'any',
        message: 'Disallow @typedef and @callback on same block.',
      },
    ],
  }],

While we could make a separate rule as well, I think those instances which are more of edge cases like this are better handled on a one-off basis, so I will close as the above should resolve it, but feel free to comment further as needed.

[remcohaszing]

There’s a misunderstanding. This issue isn’t about disallowing the combination of a @typedef tag and a @callback tag. This is about disallowing multiple @typedef tags, multiple @callback tags, or any combination of @typedef tags and @callback tags.

This happens quite a lot actually. When it breaks, the error is pretty obscure. Please have a look at the playground link and hover over the E, F, G, and H types.

[brettz9]

I believe you can get this then with the following:

  'jsdoc/no-restricted-syntax': ['error', {
    contexts: [
      {
        comment: 'JsdocBlock:has(JsdocTag[tag=typedef]):has(JsdocTag[tag=callback])',
        context: 'any',
        message: 'Disallow @typedef and @callback on same block.',
      },
      {
        comment: 'JsdocBlock:has(JsdocTag[tag=typedef] ~ JsdocTag[tag=typedef])',
        context: 'any',
        message: 'Disallow multiple @typedef on same block.',
      },
      {
        comment: 'JsdocBlock:has(JsdocTag[tag=callback] ~ JsdocTag[tag=callback])',
        context: 'any',
        message: 'Disallow multiple @typedef on same block.',
      },
    ],
  }],

[remcohaszing]

Thanks! That works.

[remcohaszing]

I’m happy there’s a way to enforce this, but I am curious why the decision is to not make this a rule. I hope I already convinced you this is not an edge case. Having worked a lot with JSDoc based types, I think this is a really common and confusing error people make.

[brettz9]

I do see that it can be quite consequential to have these on the same block, but if someone knows the problem, they are not likely to accidentally add code like this going forward. Yes, others who work on the code may not know or one may have legacy code that does this, but there is also the fact that for our project we don't want rules to proliferate so much that, besides internal complexity, it becomes hard to familiarize oneself in the docs with all the rules that are available. Knowing that tags can be disallowed together, etc., allows people to become familiar with such a rule and how to do it, and adapt it to their needs.

I would, however, be open to a PR which adds a "strict" config that inherits from recommended and has this rule defined. I think such a PR can close #701 (even though that is requesting all rules be enabled, it doesn't make sense for some rules to be enabled for all, as they may be only for specific environments, for example, so I'm really keeping that issue open for such a stricter config as I'm suggesting here). The reason I wouldn't put this config in "recommended" is because "recommended" should allow a person to define their own jsdoc/no-restricted-syntax rule.