Closed yvele closed 1 year ago
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:
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.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.
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
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).
Oh yeah I didn't get it straight but yeah it's working fine with 46.4.3 ๐ Thank you @brettz9
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:
ESLint Config
ESLint sample
but also ๐ค
Environment
eslint-plugin-jsdoc
version: 46.4.2