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

.README/rules/require-jsdoc.md

@@ -113,14 +113,30 @@ apply to any context; see `contexts` for line counts per context.
 An optional message to add to the inserted JSDoc block. Defaults to the
 empty string.
 
+### `skipInterveningOverloadedDeclarations`
+
+If `true`, will skip above uncommented overloaded functions to check
+for a comment block (e.g., at the top of a set of overloaded functions).
+
+If `false`, will force each overloaded function to be checked for a
+comment block.
+
+Defaults to `true`.
+
+### `exemptOverloadedImplementations`
+
+If set to `true` will avoid checking an overloaded function's implementation.
+
+Defaults to `false`.
+
 ## Context and settings
 
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `ClassDeclaration`, `ClassExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|N/A|
 |Recommended|true|
-|Options|`publicOnly`, `require`, `contexts`, `exemptEmptyConstructors`, `exemptEmptyFunctions`, `enableFixer`, `minLineCount`, `fixerMessage`|
+|Options|`publicOnly`, `require`, `contexts`, `exemptEmptyConstructors`, `exemptEmptyFunctions`, `enableFixer`, `minLineCount`, `fixerMessage`, `skipInterveningOverloadedDeclarations`|
 
 ## Failing examples
 

docs/rules/require-jsdoc.md

@@ -15,6 +15,8 @@
     * [`enableFixer`](#user-content-require-jsdoc-options-enablefixer)
     * [`minLineCount`](#user-content-require-jsdoc-options-minlinecount)
     * [`fixerMessage`](#user-content-require-jsdoc-options-fixermessage)
+    * [`skipInterveningOverloadedDeclarations`](#user-content-require-jsdoc-options-skipinterveningoverloadeddeclarations)
+    * [`exemptOverloadedImplementations`](#user-content-require-jsdoc-options-exemptoverloadedimplementations)
 * [Context and settings](#user-content-require-jsdoc-context-and-settings)
 * [Failing examples](#user-content-require-jsdoc-failing-examples)
 * [Passing examples](#user-content-require-jsdoc-passing-examples)
@@ -157,6 +159,26 @@ apply to any context; see `contexts` for line counts per context.
 An optional message to add to the inserted JSDoc block. Defaults to the
 empty string.
 
+<a name="user-content-require-jsdoc-options-skipinterveningoverloadeddeclarations"></a>
+<a name="require-jsdoc-options-skipinterveningoverloadeddeclarations"></a>
+### <code>skipInterveningOverloadedDeclarations</code>
+
+If `true`, will skip above uncommented overloaded functions to check
+for a comment block (e.g., at the top of a set of overloaded functions).
+
+If `false`, will force each overloaded function to be checked for a
+comment block.
+
+Defaults to `true`.
+
+<a name="user-content-require-jsdoc-options-exemptoverloadedimplementations"></a>
+<a name="require-jsdoc-options-exemptoverloadedimplementations"></a>
+### <code>exemptOverloadedImplementations</code>
+
+If set to `true` will avoid checking an overloaded function's implementation.
+
+Defaults to `false`.
+
 <a name="user-content-require-jsdoc-context-and-settings"></a>
 <a name="require-jsdoc-context-and-settings"></a>
 ## Context and settings
@@ -166,7 +188,7 @@ empty string.
 |Context|`ArrowFunctionExpression`, `ClassDeclaration`, `ClassExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|N/A|
 |Recommended|true|
-|Options|`publicOnly`, `require`, `contexts`, `exemptEmptyConstructors`, `exemptEmptyFunctions`, `enableFixer`, `minLineCount`, `fixerMessage`|
+|Options|`publicOnly`, `require`, `contexts`, `exemptEmptyConstructors`, `exemptEmptyFunctions`, `enableFixer`, `minLineCount`, `fixerMessage`, `skipInterveningOverloadedDeclarations`|
 
 <a name="user-content-require-jsdoc-failing-examples"></a>
 <a name="require-jsdoc-failing-examples"></a>
@@ -1041,6 +1063,56 @@ export class B implements A, B {
 }
 // "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["MethodDefinition"]}]
 // Message: Missing JSDoc comment.
+
+/**
+ * Test function with param.
+ * @param foo - Test param.
+ */
+function myFunction(foo: string): void;
+/**
+ * Test function without param.
+ */
+function myFunction(): void;
+function myFunction(foo?: string) {}
+// "jsdoc/require-jsdoc": ["error"|"warn", {"skipInterveningOverloadedDeclarations":false}]
+// Message: Missing JSDoc comment.
+
+/**
+ * Test function without param.
+ */
+function myFunction(): void;
+/**
+ * Test function with param.
+ * @param foo - Test param.
+ */
+function myFunction(foo: string): void;
+function myFunction(foo?: string) {}
+// "jsdoc/require-jsdoc": ["error"|"warn", {"skipInterveningOverloadedDeclarations":false}]
+// Message: Missing JSDoc comment.
+
+/**
+ * Test function with param.
+ * @param foo - Test param.
+ */
+function myFunction(foo: string): void;
+function myFunction(): void;
+/**
+ * Function implementation
+ * @param foo
+ */
+function myFunction(foo?: string) {}
+// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["TSDeclareFunction"],"exemptOverloadedImplementations":false,"skipInterveningOverloadedDeclarations":false}]
+// Message: Missing JSDoc comment.
+
+/**
+ * Test function with param.
+ * @param foo - Test param.
+ */
+function myFunction(foo: string): void;
+function myFunction(): void;
+function myFunction(foo?: string) {}
+// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["TSDeclareFunction"],"exemptOverloadedImplementations":true,"skipInterveningOverloadedDeclarations":false}]
+// Message: Missing JSDoc comment.
 ````
 
 
@@ -1944,6 +2016,7 @@ export function arrayMap<Target, Source extends Array<unknown>>(data: Source, ca
 export function arrayMap<Target, Source extends AnyArrayType>(data: Source, callback: MapCallback<Target, Source>): AnyArrayType<Target> {
   return data.map(callback);
 }
+// "jsdoc/require-jsdoc": ["error"|"warn", {"skipInterveningOverloadedDeclarations":true}]
 
 export interface A {
   a: string;
@@ -1960,5 +2033,51 @@ export class B implements A {
   }
 }
 // "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["MethodDefinition"]}]
+
+/**
+ * Test function with param.
+ * @param foo - Test param.
+ */
+function myFunction(foo: string): void;
+/**
+ * Test function without param.
+ */
+function myFunction(): void;
+function myFunction(foo?: string) {}
+
+/**
+ * Test function with param.
+ * @param foo - Test param.
+ */
+function myFunction(foo: string): void;
+/**
+ * Test function without param.
+ */
+function myFunction(): void;
+function myFunction(foo?: string) {}
+// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["TSDeclareFunction"],"exemptOverloadedImplementations":true,"skipInterveningOverloadedDeclarations":false}]
+
+/**
+ * Test function with param.
+ * @param foo - Test param.
+ */
+export function myFunction(foo: string): void;
+/**
+ * Test function without param.
+ */
+export function myFunction(): void;
+export function myFunction(foo?: string) {}
+// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["TSDeclareFunction"],"exemptOverloadedImplementations":true,"skipInterveningOverloadedDeclarations":false}]
+
+/**
+ *
+ */
+const quux = () => {
+  /**
+   *
+   */
+  function myFunction(foo?: string) {}
+};
+// "jsdoc/require-jsdoc": ["error"|"warn", {"exemptOverloadedImplementations":true,"require":{"ArrowFunctionExpression":true}}]
 ````
 

docs/rules/require-param.md

@@ -1842,5 +1842,16 @@ const inner = (c: number, d: string): void => {
  */
 function quux (a, b) {}
 // "jsdoc/require-param": ["error"|"warn", {"ignoreWhenAllParamsMissing":true}]
+
+/**
+ * Test function with param.
+ * @param foo - Test param.
+ */
+function myFunction(foo: string): void;
+/**
+ * Test function without param.
+ */
+function myFunction(): void;
+function myFunction(foo?: string) {}
 ````
 

package.json

@@ -5,7 +5,7 @@
     "url": "http://gajus.com"
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "~0.53.0",
+    "@es-joy/jsdoccomment": "~0.54.0",
     "are-docs-informative": "^0.0.2",
     "comment-parser": "1.4.1",
     "debug": "^4.4.1",

src/index.js

@@ -137,7 +137,7 @@ const index = {
 /**
  * @param {"warn"|"error"} warnOrError
  * @param {string} [flatName]
- * @returns {import('eslint').Linter.FlatConfig}
+ * @returns {import('eslint').Linter.Config}
  */
 const createRecommendedRuleset = (warnOrError, flatName) => {
   return {
@@ -216,7 +216,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
 /**
  * @param {"warn"|"error"} warnOrError
  * @param {string} [flatName]
- * @returns {import('eslint').Linter.FlatConfig}
+ * @returns {import('eslint').Linter.Config}
  */
 const createRecommendedTypeScriptRuleset = (warnOrError, flatName) => {
   const ruleset = createRecommendedRuleset(warnOrError, flatName);
@@ -244,7 +244,7 @@ const createRecommendedTypeScriptRuleset = (warnOrError, flatName) => {
 /**
  * @param {"warn"|"error"} warnOrError
  * @param {string} [flatName]
- * @returns {import('eslint').Linter.FlatConfig}
+ * @returns {import('eslint').Linter.Config}
  */
 const createRecommendedTypeScriptFlavorRuleset = (warnOrError, flatName) => {
   const ruleset = createRecommendedRuleset(warnOrError, flatName);
@@ -267,7 +267,7 @@ const createStandaloneRulesetFactory = (ruleNames) => {
   /**
    * @param {"warn"|"error"} warnOrError
    * @param {string} [flatName]
-   * @returns {import('eslint').Linter.FlatConfig}
+   * @returns {import('eslint').Linter.Config}
    */
   return (warnOrError, flatName) => {
     return {
@@ -411,7 +411,7 @@ index.configs['flat/stylistic-typescript-error'] = createStylisticTypeScriptRule
 index.configs['flat/stylistic-typescript-flavor'] = createStylisticTypeScriptFlavorRuleset('warn', 'flat/stylistic-typescript-flavor');
 index.configs['flat/stylistic-typescript-flavor-error'] = createStylisticTypeScriptFlavorRuleset('error', 'flat/stylistic-typescript-error-flavor');
 
-index.configs.examples = /** @type {import('eslint').Linter.FlatConfig[]} */ ([
+index.configs.examples = /** @type {import('eslint').Linter.Config[]} */ ([
   {
     files: [
       '**/*.js',
@@ -465,7 +465,7 @@ index.configs.examples = /** @type {import('eslint').Linter.FlatConfig[]} */ ([
   },
 ]);
 
-index.configs['default-expressions'] = /** @type {import('eslint').Linter.FlatConfig[]} */ ([
+index.configs['default-expressions'] = /** @type {import('eslint').Linter.Config[]} */ ([
   {
     files: [
       '**/*.js',
@@ -502,7 +502,7 @@ index.configs['default-expressions'] = /** @type {import('eslint').Linter.FlatCo
   },
 ]);
 
-index.configs['examples-and-default-expressions'] = /** @type {import('eslint').Linter.FlatConfig[]} */ ([
+index.configs['examples-and-default-expressions'] = /** @type {import('eslint').Linter.Config[]} */ ([
   {
     name: 'jsdoc/examples-and-default-expressions',
     plugins: {