check-tag-names should include "@rejects" by default

[Zamiell]

The newly implemented "jsdoc/require-rejects" rule enforces that functions that have a promise rejection have a @rejects tag.

I added this rule to my codebase for the first time today and it found a few errors. However, as soon as I tried to fix them by adding a @rejects tag, I immediately got another error from "jsdoc/check-tag-names" because @rejects is not a standard JSDoc tag. Annoying!

In order to fix this now unfixable lint error, users must set a custom configuration for "check-tag-names" to explicitly include "rejects" in the definedTags section. But forcing everyone across the ecosystem to do this is super painful. Thus, I propose that the check-tag-names rule include @rejects by default to prevent users from having to deal with this.

Counterargument

I assume the reason that this is not done already is that @rejects is technically a non-standard tag. We should consider users who use "check-tag-names" but do not use "require-rejects". For those users, it would be weird for them if @rejects was allowed, because then, non-standard JSDoc tags could slip into their codebases.

With that said, I don't think this counter-argument is very convincing. Since we have made the decision to go forward and publish the official "require-rejects" rule in this plugin, I think that the ecosystem should standardize around this convention, and that it should be treated as an "official" tag henceforth.

Thoughts?

[brettz9]

If you use the recommended procedural approach, e.g.,

import {jsdoc} from 'eslint-plugin-jsdoc';

export default [
  jsdoc({
    config: 'flat/recommended'
  });
]

...the non-standard @rejects as well as @next should be predefined for you.

[Zamiell]

Ah, I didn't know that the recommended config customizes the the check-tag-names rule. That's interesting!

I don't use the recommended config - I explicitly turn on all of the jsdoc rules that I want. And I think that many other users do the same.

Furthermore, I don't think that "good defaults" should be part of a config, because anyone who just uses the rule directly will miss out. Also, I think that it is a pretty confusing design! As a user who uses the recommended config, I would be scratching my head if I wanted to further customize the rule. I would be left wondering: "What default options are coming from the rule and what default options are coming from the config?"

Do other ESLint plugins in the ecosystem do this in their recommended configs? I don't think I've ever seen this done before.

I propose that whatever option customizations that we put in the recommended config should be taken out of that config and instead made to be default options on the check-tag-names rule itself. That way, all users will benefit automatically and the design is simplified.

[brettz9]

Ah, I didn't know that the recommended config customizes the the check-tag-names rule.

It's actually not the recommended config that is doing that but the default settings applied as part of the procedural jsdoc call.

I don't use the recommended config - I explicitly turn on all of the jsdoc rules that I want. And I think that many other users do the same.

The procedural approach can be supplied rules as well. The procedural approach allows for Intellisense/autocomplete on rules, configs, and options.

Furthermore, I don't think that "good defaults" should be part of a config, because anyone who just uses the rule directly will miss out. Also, I think that it is a pretty confusing design! As a user who uses the recommended config, I would be scratching my head if I wanted to further customize the rulle: "What default options are coming from the rule and what default options are coming from the config?"

Do other ESLint plugins in the ecosystem do this in their recommended configs? I don't think I've ever seen this done before.

I propose that whatever option customizations that we put in the recommended config should be taken out of that config and instead made to be default options on the check-tag-names rule itself. That way, all users will benefit automatically and the design is simplified.

I am a bit hesitant to force users of the rule to accept these as defaults since they are non-standard. However, I do agree it makes sense as a default behavior, and the recommended approach of using the procedural API is to provide settings by default which treats @next and @rejects as defined, so I think the behavior should work well for most who are following the recommended approach and who are not overriding the settings so that they can say avoid @rejects being defined. It's not the config that does this, but the procedural approach. It also keeps check-tag-names from introducing its own non-standard behavior (except where settings are defined).

We may deprecate direct use of configs and rules at some point and just require the procedural approach, so that is why I am not finding such a problem with this inconsistency between procedural and non-procedural (and actually it is somewhat consistent because it depends either way on what one's settings are).

[brettz9]

Closing for now, though we might revisit the deprecation of the non-procedural configs.