feat(require-jsdoc): add on-by-default skipInterveningOverloadedDeclarations option

[brettz9]

feat(require-jsdoc): add on-by-default skipInterveningOverloadedDeclarations option; fixes #1434

BREAKING CHANGE:

Now requires skipInterveningOverloadedDeclarations: true option to get behavior of checking at the top of overloaded functions from #1369

[Copilot]

Pull Request Overview

This PR adds a new skipInterveningOverloadedDeclarations option to the require-jsdoc rule that controls whether the rule should skip checking overloaded function declarations for JSDoc comments when a comment exists on a preceding overload. The option defaults to true, which is a breaking change from the previous behavior.

• Adds skipInterveningOverloadedDeclarations boolean option with default value of true
• Updates the getJSDocComment call to pass the checkOverloads parameter based on this option
• Updates package dependency @es-joy/jsdoccomment from ~0.53.0 to ~0.54.0

Reviewed Changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/rules/requireJsdoc.js	Adds the new option schema, parameter handling, and passes checkOverloads to getJSDocComment
test/rules/assertions/requireJsdoc.js	Adds test cases for both enabled and disabled skipInterveningOverloadedDeclarations behavior
test/rules/assertions/requireParam.js	Adds a test case showing the new default behavior for overloaded functions
docs/rules/require-jsdoc.md	Documents the new option with examples and updates the options table
.README/rules/require-jsdoc.md	Updates the README template with the new option documentation
docs/rules/require-param.md	Adds an example showing the new behavior
package.json	Updates the @es-joy/jsdoccomment dependency version

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[otomad]

I tested it and it almost suitable for my use cases.

It would be fine if there is an additional option skipImplementationOverloadedDeclarations, which does the opposite of skipInterveningOverloadedDeclarations, which is used to skip documenting the implementation declaration of overloaded functions.

My current rule is to document every overload declarations, but not the implementation. This is also how VSCode displays documentation when you hover the pointer over a variable: it only shows the documentation for the overloads, not the implementation. Even if you hover the pointer over the implementation function itself, it will still show the documentation of the first overload.

Of course, you can also ignore it if it's difficult to implement, because it already suitable for my use cases now.