fix(check-param-names): check against whitelist of acceptable function nodes so that non-function global contexts do not err; fixes #1303

Also adds warning in docs for use of global settings contexts.

Author: brettz9

.README/settings.md

@@ -329,5 +329,9 @@ values are objects with the following optional properties:
 ### `contexts`
 
 `settings.jsdoc.contexts` can be used as the default for any rules
-with a `contexts` property option. See the "AST and Selectors" section
-for more on this format.
+with a `contexts` property option. **Please note**: This will replace any
+default contexts, including for function rules, so if, for example, you exclude
+`FunctionDeclaration` here, rules like `require-param` will not check
+function declarations.
+
+See the "AST and Selectors" section for more on this format.

docs/rules/check-param-names.md

@@ -1119,5 +1119,15 @@ function quux (foo, bar) {
 export function fn(...[type, arg]: FnArgs): void {
   // ...
 }
+
+/**
+ * @param c c
+ * @param d d
+ */
+const inner = (c: number, d: string): void => {
+  console.log(c);
+  console.log(d);
+};
+// Settings: {"jsdoc":{"contexts":["VariableDeclaration"]}}
 ````
 

docs/rules/require-param.md

@@ -1804,5 +1804,14 @@ function a (b) {}
 function sumDestructure(this: unknown, { a, b }: { a: number, b: number }) {
   return a + b;
 }
+
+/**
+ *
+ */
+const inner = (c: number, d: string): void => {
+  console.log(c);
+  console.log(d);
+};
+// Settings: {"jsdoc":{"contexts":["VariableDeclaration"]}}
 ````
 

docs/settings.md

@@ -358,5 +358,9 @@ values are objects with the following optional properties:
 ### <code>contexts</code>
 
 `settings.jsdoc.contexts` can be used as the default for any rules
-with a `contexts` property option. See the "AST and Selectors" section
-for more on this format.
+with a `contexts` property option. **Please note**: This will replace any
+default contexts, including for function rules, so if, for example, you exclude
+`FunctionDeclaration` here, rules like `require-param` will not check
+function declarations.
+
+See the "AST and Selectors" section for more on this format.

src/rules/checkParamNames.js

@@ -354,11 +354,18 @@ const validateParameterNamesDeep = (
   });
 };
 
+const allowedNodes = [
+  'ArrowFunctionExpression', 'FunctionDeclaration', 'FunctionExpression', 'TSDeclareFunction',
+    // Add this to above defaults
+    'TSMethodSignature'
+];
+
 export default iterateJsdoc(({
   context,
   jsdoc,
   report,
   utils,
+  node,
 }) => {
   const {
     allowExtraTrailingParamDocs,
@@ -371,6 +378,15 @@ export default iterateJsdoc(({
     disableMissingParamChecks = false,
   } = context.options[0] || {};
 
+  // Although we might just remove global settings contexts from applying to
+  //   this rule (as they can cause problems with `getFunctionParameterNames`
+  //   checks if they are not functions but say variables), the user may
+  //   instead wish to narrow contexts in those settings, so this check
+  //   is still useful
+  if (!allowedNodes.includes(/** @type {import('estree').Node} */ (node).type)) {
+    return;
+  }
+
   const checkTypesRegex = utils.getRegexFromString(checkTypesPattern);
 
   const jsdocParameterNamesDeep = utils.getJsdocTagsDeep('param');
@@ -406,11 +422,7 @@ export default iterateJsdoc(({
     targetTagName, allowExtraTrailingParamDocs, jsdocParameterNamesDeep, jsdoc, report,
   );
 }, {
-  contextDefaults: [
-    'ArrowFunctionExpression', 'FunctionDeclaration', 'FunctionExpression', 'TSDeclareFunction',
-    // Add this to above defaults
-    'TSMethodSignature'
-  ],
+  contextDefaults: allowedNodes,
   meta: {
     docs: {
       description: 'Ensures that parameter names in JSDoc match those in the function declaration.',

test/rules/assertions/checkParamNames.js

@@ -2015,5 +2015,28 @@ export default {
         sourceType: 'module',
       },
     },
+    {
+      code: `
+        /**
+         * @param c c
+         * @param d d
+         */
+        const inner = (c: number, d: string): void => {
+          console.log(c);
+          console.log(d);
+        };
+      `,
+      languageOptions: {
+        parser: typescriptEslintParser,
+        sourceType: 'module',
+      },
+      settings: {
+        jsdoc: {
+          contexts: [
+            'VariableDeclaration',
+          ]
+        }
+      },
+    },
   ],
 };

test/rules/assertions/requireParam.js

@@ -3582,5 +3582,27 @@ export default {
         parser: typescriptEslintParser,
       },
     },
+    {
+      code: `
+        /**
+         *
+         */
+        const inner = (c: number, d: string): void => {
+          console.log(c);
+          console.log(d);
+        };
+      `,
+      languageOptions: {
+        parser: typescriptEslintParser,
+        sourceType: 'module',
+      },
+      settings: {
+        jsdoc: {
+          contexts: [
+            'VariableDeclaration',
+          ]
+        }
+      },
+    },
   ],
 };