With 46.4.2 match-description reports error when require-description is off

[yvele]

Expected behavior

"jsdoc/require-description" : "off" should overrule "jsdoc/match-description"

This works with v46.2.6 👍
And does not work anymore with v46.4.2 👎

Actual behavior

I've juste updated my eslint-plugin-jsdoc dependency from v46.2.6 to v46.4.2 and now i have this error popping everywhere:

error JSDoc description must not be empty jsdoc/match-description

ESLint Config

  plugins : [
    "jsdoc"
  ],
  rules : {

    // Don't require a description
    "jsdoc/require-description" : "off",

    // Enforces a regular expression pattern on descriptions.
    "jsdoc/match-description" : ["error", {
      // The default is this basic expression to match English sentences
      // that does not necessarily ends with a dot
      matchDescription : "^([A-Z]|[`\\d_])[\\s\\S]"
    }]

}

ESLint sample

/**
 * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase
 * @returns {Function} Middleware function
 * @throws {ArgumentNullError}
 * @throws {ArgumentError}
 */
export default function isUpperCase() {
  ...
}

but also 🤔

/**
 * Validate that a string is all uppercase.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase
 * @returns {Function} Middleware function
 * @throws {ArgumentNullError}
 * @throws {ArgumentError}
 */
export default function isUpperCase() {
  ...
}

Environment

• Node version: v18.15.0
• ESLint version v8.43.0
• eslint-plugin-jsdoc version: 46.4.2

[brettz9]

Thanks for the report.

First a point of clarification. With the exception of the marking of unused variables, ESLint rules should not influence one another, so despite appearances, jsdoc/require-description has never influenced jsdoc/match-description.

However, there were indeed some recent changes to match-description which made it more aggressive (and indeed too aggressive).

I submitted #1127 to stop reporting missing descriptions for @throws (and @yields) which was probably the source of your grief, so you might try 46.4.3 to see if you are satisfied with the changes.

Note that the match-description rule will still have the following new, more aggressive behaviors:

1. Enforce the default initial-caps regular expression on the following tags (unless one supplies one's own match for them on tags): 'description', 'summary', 'file', and 'classdesc'. Although match-description does not report missing descriptions for block descriptions (it only reports when a block description is present and fails to match), it does now expect descriptions to match if these tags are present at all, with the rationale that these tags should probably not be present if they are blank. The tags are also expected to follow the match-description desired sentence structure (e.g., initial caps) when a description is present.
2. Enforces a simple, non-empty regular expression on the following tags unless the new option nonemptyTags is set to false: 'copyright', 'example', 'see', 'todo'. It is figured that if these tags are present at all, they should not be empty, though they might not follow normal sentence structure so the check on them is just that some description exists.

For no. 2, this new functionality could admittedly have been placed in require-description, but I figured require-description could be kept more simple.

Feedback is welcome on whether the changes are still felt to be somehow too aggressive even with throws and yields now dropped. FWIW, the rationale for originally including these tags was that if one wanted more descriptive control as shown by enabling the rule, these tags could also use descriptions, but since the rule previously did not report errors when a description was entirely missing, this change ended up being too aggressive. We could still enforce the regular expression for these tags when only a description for them is present, but perhaps people might not care to have, e.g., upper-case sentences enforced with throws or yields even if they do want them for block descriptions.

[yvele]

ok @brettz9 thanks for the clarification.
So this change is breaking and should have been published as a v47 🙏
How could I have the same behavior as I always had with eslint-plugin-jsdoc before this new "aggressive" change?
How could I have a regex enforcing the description layout but with an optional description?
Thank you

[brettz9]

ok @brettz9 thanks for the clarification. So this change is breaking and should have been published as a v47 🙏

As with ESLint itself, we don't and haven't followed semver in exactly such a manner. New features, as this was, will possibly cause new breakage in some cases if by "breakage" is understood new linting failures. We tend to use major version changes for changes where existing behavior has changed, e.g., an existing option or rule is removed. If you want to minimize the chances of new linting failures, you can pin to the minor version (or if you really want to be cautious, the patch version, though I wouldn't expect that normally to be necessary).

How could I have the same behavior as I always had with eslint-plugin-jsdoc before this new "aggressive" change? How could I have a regex enforcing the description layout but with an optional description? Thank you

Have you tried the new version? By "more aggressive", I just mean capable of catching more errors, not that the changes are unreasonable (besides the issue before the fix in v46.4.3). I don't think the aggressive changes are likely to cause a problem for you, but if they are, only the second type of change I mentioned can be undone, namely by setting nonemptyTags to false. For the first type of change, I don't think there should be any need to give a way to undo this change (since I doubt people will want to keep tags like @description without content--that item only applies to tag descriptions, not to the block description).

[yvele]

Oh yeah I didn't get it straight but yeah it's working fine with 46.4.3 👍
Thank you @brettz9