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

Author: brettz9

.README/rules/require-jsdoc.md

@@ -113,14 +113,20 @@ 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).
+Defaults to `true`.
+
 ## 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,7 @@
     * [`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)
 * [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 +158,14 @@ 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).
+Defaults to `true`.
+
 <a name="user-content-require-jsdoc-context-and-settings"></a>
 <a name="require-jsdoc-context-and-settings"></a>
 ## Context and settings
@@ -166,7 +175,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 +1050,32 @@ 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.
 ````
 
 
@@ -1944,6 +1979,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 +1996,16 @@ 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) {}
 ````
 

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",
@@ -40,7 +40,7 @@
     "@types/json-schema": "^7.0.15",
     "@types/lodash.defaultsdeep": "^4.6.9",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^24.2.1",
+    "@types/node": "^24.3.0",
     "@types/semver": "^7.7.0",
     "@types/spdx-expression-parse": "^3.0.5",
     "@typescript-eslint/types": "^8.39.1",

pnpm-lock.yaml

@@ -169,6 +169,10 @@ const OPTIONS_SCHEMA = {
       },
       type: 'object',
     },
+    skipInterveningOverloadedDeclarations: {
+      default: true,
+      type: 'boolean',
+    },
   },
   type: 'object',
 };
@@ -302,6 +306,7 @@ const getOption = (context, baseObject, option, key) => {
  *   enableFixer: boolean,
  *   exemptEmptyConstructors: boolean,
  *   exemptEmptyFunctions: boolean,
+ *   skipInterveningOverloadedDeclarations: boolean,
  *   fixerMessage: string,
  *   minLineCount: undefined|import('../iterateJsdoc.js').Integer,
  *   publicOnly: boolean|{[key: string]: boolean|undefined}
@@ -317,6 +322,7 @@ const getOptions = (context, settings) => {
     fixerMessage = '',
     minLineCount = undefined,
     publicOnly,
+    skipInterveningOverloadedDeclarations = true,
   } = context.options[0] || {};
 
   return {
@@ -386,6 +392,7 @@ const getOptions = (context, settings) => {
       /** @type {import('json-schema').JSONSchema4Object} */
       (OPTIONS_SCHEMA.properties).require,
     ),
+    skipInterveningOverloadedDeclarations,
   };
 };
 
@@ -411,6 +418,7 @@ export default {
       fixerMessage,
       minLineCount,
       require: requireOption,
+      skipInterveningOverloadedDeclarations,
     } = opts;
 
     const publicOnly =
@@ -476,7 +484,11 @@ export default {
         }
       }
 
-      const jsDocNode = getJSDocComment(sourceCode, node, settings);
+      const jsDocNode = getJSDocComment(
+        sourceCode, node, settings, {
+          checkOverloads: skipInterveningOverloadedDeclarations,
+        },
+      );
 
       if (jsDocNode) {
         return;