feat(require-param): add interfaceExemptsParamsCheck option; fixes #1511 (#1521)

brettz9 · web-flow · commit a3bb85e6faba · 2025-09-16T18:56:43.000+08:00
diff --git a/.README/rules/require-param.md b/.README/rules/require-param.md
@@ -374,6 +374,15 @@ supplied as default values. Defaults to `false`.
 Set to `true` to ignore reporting when all params are missing. Defaults to
 `false`.
 
+### `interfaceExemptsParamsCheck`
+
+Set if you wish TypeScript interfaces to exempt checks for the existence of
+`@param`'s.
+
+Will check for a type defining the function itself (on a variable
+declaration) or if there is a single destructured object with a type.
+Defaults to `false`.
+
 ## Context and settings
 
 |          |                      |
@@ -382,7 +391,7 @@ Set to `true` to ignore reporting when all params are missing. Defaults to
 | Tags     | `param` |
 | Aliases  | `arg`, `argument` |
 |Recommended | true|
-| Options  |`autoIncrementBase`, `checkConstructors`, `checkDestructured`, `checkDestructuredRoots`, `checkGetters`, `checkRestProperty`, `checkSetters`, `checkTypesPattern`, `contexts`, `enableFixer`, `enableRestElementFixer`, `enableRootFixer`, `exemptedBy`, `ignoreWhenAllParamsMissing`, `unnamedRootBase`, `useDefaultObjectProperties`|
+| Options  |`autoIncrementBase`, `checkConstructors`, `checkDestructured`, `checkDestructuredRoots`, `checkGetters`, `checkRestProperty`, `checkSetters`, `checkTypesPattern`, `contexts`, `enableFixer`, `enableRestElementFixer`, `enableRootFixer`, `exemptedBy`, `ignoreWhenAllParamsMissing`, `interfaceExemptsParamsCheck`, `unnamedRootBase`, `useDefaultObjectProperties`|
 | Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
 
 ## Failing examples
diff --git a/docs/rules/require-param.md b/docs/rules/require-param.md
@@ -24,6 +24,7 @@
     * [`checkDestructuredRoots`](#user-content-require-param-options-checkdestructuredroots)
     * [`useDefaultObjectProperties`](#user-content-require-param-options-usedefaultobjectproperties)
     * [`ignoreWhenAllParamsMissing`](#user-content-require-param-options-ignorewhenallparamsmissing)
+    * [`interfaceExemptsParamsCheck`](#user-content-require-param-options-interfaceexemptsparamscheck)
 * [Context and settings](#user-content-require-param-context-and-settings)
 * [Failing examples](#user-content-require-param-failing-examples)
 * [Passing examples](#user-content-require-param-passing-examples)
@@ -445,6 +446,17 @@ supplied as default values. Defaults to `false`.
 Set to `true` to ignore reporting when all params are missing. Defaults to
 `false`.
 
+<a name="user-content-require-param-options-interfaceexemptsparamscheck"></a>
+<a name="require-param-options-interfaceexemptsparamscheck"></a>
+### <code>interfaceExemptsParamsCheck</code>
+
+Set if you wish TypeScript interfaces to exempt checks for the existence of
+`@param`'s.
+
+Will check for a type defining the function itself (on a variable
+declaration) or if there is a single destructured object with a type.
+Defaults to `false`.
+
 <a name="user-content-require-param-context-and-settings"></a>
 <a name="require-param-context-and-settings"></a>
 ## Context and settings
@@ -455,7 +467,7 @@ Set to `true` to ignore reporting when all params are missing. Defaults to
 | Tags     | `param` |
 | Aliases  | `arg`, `argument` |
 |Recommended | true|
-| Options  |`autoIncrementBase`, `checkConstructors`, `checkDestructured`, `checkDestructuredRoots`, `checkGetters`, `checkRestProperty`, `checkSetters`, `checkTypesPattern`, `contexts`, `enableFixer`, `enableRestElementFixer`, `enableRootFixer`, `exemptedBy`, `ignoreWhenAllParamsMissing`, `unnamedRootBase`, `useDefaultObjectProperties`|
+| Options  |`autoIncrementBase`, `checkConstructors`, `checkDestructured`, `checkDestructuredRoots`, `checkGetters`, `checkRestProperty`, `checkSetters`, `checkTypesPattern`, `contexts`, `enableFixer`, `enableRestElementFixer`, `enableRootFixer`, `exemptedBy`, `ignoreWhenAllParamsMissing`, `interfaceExemptsParamsCheck`, `unnamedRootBase`, `useDefaultObjectProperties`|
 | Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
 
 <a name="user-content-require-param-failing-examples"></a>
@@ -1185,6 +1197,25 @@ function quux (a, b) {}
 export type Test = (foo: number) => string;
 // "jsdoc/require-param": ["error"|"warn", {"contexts":["TSFunctionType"]}]
 // Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ *
+ */
+const quux = function quux (foo) {
+};
+// "jsdoc/require-param": ["error"|"warn", {"interfaceExemptsParamsCheck":true}]
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ *
+ */
+function quux ({
+  abc,
+  def
+}) {
+}
+// "jsdoc/require-param": ["error"|"warn", {"interfaceExemptsParamsCheck":true}]
+// Message: Missing JSDoc @param "root0" declaration.
 ````
 
 
@@ -1853,5 +1884,22 @@ function myFunction(foo: string): void;
  */
 function myFunction(): void;
 function myFunction(foo?: string) {}
+
+/**
+ *
+ */
+const quux: FunctionInterface = function quux (foo) {
+};
+// "jsdoc/require-param": ["error"|"warn", {"interfaceExemptsParamsCheck":true}]
+
+/**
+ *
+ */
+function quux ({
+  abc,
+  def
+}: FunctionInterface) {
+}
+// "jsdoc/require-param": ["error"|"warn", {"interfaceExemptsParamsCheck":true}]
 ````
 
diff --git a/src/rules.d.ts b/src/rules.d.ts
@@ -591,6 +591,7 @@ export interface Rules {
           enableRootFixer?: boolean;
           exemptedBy?: string[];
           ignoreWhenAllParamsMissing?: boolean;
+          interfaceExemptsParamsCheck?: boolean;
           unnamedRootBase?: string[];
           useDefaultObjectProperties?: boolean;
         }
diff --git a/src/rules/requireParam.js b/src/rules/requireParam.js
@@ -35,6 +35,7 @@ const rootNamer = (desiredRoots, currentIndex) => {
 export default iterateJsdoc(({
   context,
   jsdoc,
+  node,
   utils,
 }) => {
   /* eslint-enable complexity -- Temporary */
@@ -57,12 +58,28 @@ export default iterateJsdoc(({
     enableRestElementFixer = true,
     enableRootFixer = true,
     ignoreWhenAllParamsMissing = false,
+    interfaceExemptsParamsCheck = false,
     unnamedRootBase = [
       'root',
     ],
     useDefaultObjectProperties = false,
   } = context.options[0] || {};
 
+  if (interfaceExemptsParamsCheck) {
+    if (node && 'params' in node && node.params.length === 1 &&
+        node.params?.[0] && typeof node.params[0] === 'object' &&
+        node.params[0].type === 'ObjectPattern' &&
+        'typeAnnotation' in node.params[0] && node.params[0].typeAnnotation
+    ) {
+      return;
+    }
+
+    if (node && node.parent.type === 'VariableDeclarator' &&
+        'typeAnnotation' in node.parent.id && node.parent.id.typeAnnotation) {
+      return;
+    }
+  }
+
   const preferredTagName = /** @type {string} */ (utils.getPreferredTagName({
     tagName: 'param',
   }));
@@ -579,6 +596,9 @@ export default iterateJsdoc(({
           ignoreWhenAllParamsMissing: {
             type: 'boolean',
           },
+          interfaceExemptsParamsCheck: {
+            type: 'boolean',
+          },
           unnamedRootBase: {
             items: {
               type: 'string',
diff --git a/test/rules/assertions/requireParam.js b/test/rules/assertions/requireParam.js
@@ -2587,6 +2587,87 @@ export default /** @type {import('../index.js').TestCases} */ ({
         export type Test = (foo: number) => string;
       `,
     },
+    {
+      code: `
+          /**
+           *
+           */
+          const quux = function quux (foo) {
+          };
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @param "foo" declaration.',
+        },
+      ],
+      languageOptions: {
+        parser: typescriptEslintParser,
+        sourceType: 'module',
+      },
+      options: [
+        {
+          interfaceExemptsParamsCheck: true,
+        },
+      ],
+      output: `
+          /**
+           *
+           * @param foo
+           */
+          const quux = function quux (foo) {
+          };
+      `,
+    },
+
+    {
+      code: `
+          /**
+           *
+           */
+          function quux ({
+            abc,
+            def
+          }) {
+          }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @param "root0" declaration.',
+        },
+        {
+          line: 2,
+          message: 'Missing JSDoc @param "root0.abc" declaration.',
+        },
+        {
+          line: 2,
+          message: 'Missing JSDoc @param "root0.def" declaration.',
+        },
+      ],
+      languageOptions: {
+        parser: typescriptEslintParser,
+        sourceType: 'module',
+      },
+      options: [
+        {
+          interfaceExemptsParamsCheck: true,
+        },
+      ],
+      output: `
+          /**
+           *
+           * @param root0
+           * @param root0.abc
+           * @param root0.def
+           */
+          function quux ({
+            abc,
+            def
+          }) {
+          }
+      `,
+    },
   ],
   valid: [
     {
@@ -3695,5 +3776,45 @@ export default /** @type {import('../index.js').TestCases} */ ({
         sourceType: 'module',
       },
     },
+    {
+      code: `
+          /**
+           *
+           */
+          const quux: FunctionInterface = function quux (foo) {
+          };
+      `,
+      languageOptions: {
+        parser: typescriptEslintParser,
+        sourceType: 'module',
+      },
+      options: [
+        {
+          interfaceExemptsParamsCheck: true,
+        },
+      ],
+    },
+
+    {
+      code: `
+          /**
+           *
+           */
+          function quux ({
+            abc,
+            def
+          }: FunctionInterface) {
+          }
+      `,
+      languageOptions: {
+        parser: typescriptEslintParser,
+        sourceType: 'module',
+      },
+      options: [
+        {
+          interfaceExemptsParamsCheck: true,
+        },
+      ],
+    },
   ],
 });

Original file line number	Diff line number	Diff line change
`@@ -591,6 +591,7 @@ export interface Rules {`
`591`	`591`	`enableRootFixer?: boolean;`
`592`	`592`	`exemptedBy?: string[];`
`593`	`593`	`ignoreWhenAllParamsMissing?: boolean;`
	`594`	`+ interfaceExemptsParamsCheck?: boolean;`
`594`	`595`	`unnamedRootBase?: string[];`
`595`	`596`	`useDefaultObjectProperties?: boolean;`
`596`	`597`	`}`