Require description on `@deprecated` tag

[ericcornelissen]

Motivation

@deprecated tags should probably always to have a description, so this should be enforcable similar to e.g. require-param-description.

This appears to be mentioned in #233, but I wanted to open this to track the @deprecated tag explicitly (and because it might be easier to find for future reference as a standalone).

Current behavior

There is no such rule.

Desired behavior

Create a require-deprecated-description that enforces @deprecated tags have a (non-empty( description.

Alternatives considered

As discussed in #911, the match-description rule could be used to enforce this. However, the following did not appear to actually enforce @deprecated tag descriptions when I tested it 😕

      "jsdoc/match-description": [
        "error",
        {
          mainDescription: "^[A-Z`\\d][\\s\\S]*.\n$",
          tags: {
            deprecated: "^[A-Z].*\\.$",
            param: "^[A-Z].*\\.$",
            returns: "^[A-Z`].*\\.$",
            since: "^[0-9]\\.[0-9]\\.[0-9]",
            throws: "^[A-Z].*\\.$",
            yields: "^[A-Z`].*\\.$",
          },
        },
      ],

[brettz9]

Alternatives considered

As discussed in #911, the match-description rule could be used to enforce this. However, the following did not appear to actually enforce @deprecated tag descriptions when I tested it 😕

  "jsdoc/match-description": [
    "error",
    {
      mainDescription: "^[A-Z`\\d][\\s\\S]*.\n$",
      tags: {
        deprecated: "^[A-Z].*\\.$",
        param: "^[A-Z].*\\.$",
        returns: "^[A-Z`].*\\.$",
        since: "^[0-9]\\.[0-9]\\.[0-9]",
        throws: "^[A-Z].*\\.$",
        yields: "^[A-Z`].*\\.$",
      },
    },
  ],

You need to add contexts (e.g., contexts: ['any']) as this rule only applies to functions by default.

[ericcornelissen]

You need to add contexts (e.g., contexts: ['any']) as this rule only applies to functions by default.

Thanks for clarifying, that worked for me. I'll leave this open for you to decide if you'd want to add a rule like this still.

[brettz9]

I'll go ahead and close, as I think we need to be conservative with the addition of rules when there is an alternative.