From 0cd761b504b3f07acd6c5045e2fa9b5a0cb27e2c Mon Sep 17 00:00:00 2001
From: Brett Zamir <brettz9@yahoo.com>
Date: Wed, 24 Jan 2024 09:14:11 -0700
Subject: [PATCH] fix(`require-param`): skip `this` parameter in checks (when
 followed by destructured content); fixes #1190

---
 docs/rules/require-jsdoc.md           | 10 ++++++++++
 docs/rules/require-param.md           | 11 +++++++++++
 src/rules/requireParam.js             |  6 ++++--
 test/rules/assertions/requireParam.js | 17 +++++++++++++++++
 4 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/docs/rules/require-jsdoc.md b/docs/rules/require-jsdoc.md
index 93b068929..5f120d084 100644
--- a/docs/rules/require-jsdoc.md
+++ b/docs/rules/require-jsdoc.md
@@ -1016,6 +1016,16 @@ export class MyClass {
 export const Comp = observer(() => <>Hello</>);
 // "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["CallExpression[callee.name=\"observer\"]"],"enableFixer":false,"publicOnly":true,"require":{"ArrowFunctionExpression":true,"ClassDeclaration":true,"ClassExpression":true,"FunctionDeclaration":true,"FunctionExpression":true,"MethodDefinition":true}}]
 // Message: Missing JSDoc comment.
+
+/**
+ * Command options for the login command
+ */
+export type LoginOptions = CmdOptions<{
+  username?: string;
+  password?: string;
+}>;
+// "jsdoc/require-jsdoc": ["error"|"warn", {"publicOnly":{"ancestorsOnly":true},"contexts":["TSTypeAliasDeclaration","TSInterfaceDeclaration","TSMethodSignature","TSPropertySignature"]}]
+// Message: Missing JSDoc comment.
 ````
 
 
diff --git a/docs/rules/require-param.md b/docs/rules/require-param.md
index eeb88e5d8..bf4ebfe17 100644
--- a/docs/rules/require-param.md
+++ b/docs/rules/require-param.md
@@ -1832,5 +1832,16 @@ function foo(this: T, bar: number): number {
 /** {@link someOtherval} */
 function a (b) {}
 // "jsdoc/require-param": ["error"|"warn", {"contexts":[{"comment":"*:not(JsdocBlock:has(JsdocInlineTag[tag=link]))","context":"FunctionDeclaration"}]}]
+
+/**
+ * Returns the sum of two numbers
+ * @param options Object to destructure
+ * @param options.a First value
+ * @param options.b Second value
+ * @returns Sum of a and b
+ */
+function sumDestructure(this: unknown, { a, b }: { a: number, b: number }) {
+  return a + b;
+}
 ````
 
diff --git a/src/rules/requireParam.js b/src/rules/requireParam.js
index 2ab5ba4a0..7be64b952 100644
--- a/src/rules/requireParam.js
+++ b/src/rules/requireParam.js
@@ -214,14 +214,16 @@ export default iterateJsdoc(({
     ...unnamedRootBase,
   ], autoIncrementBase);
 
+  const thisOffset = functionParameterNames[0] === 'this' ? 1 : 0;
+
   for (const [
     functionParameterIdx,
     functionParameterName,
   ] of functionParameterNames.entries()) {
     let inc;
     if (Array.isArray(functionParameterName)) {
-      const matchedJsdoc = shallowJsdocParameterNames[functionParameterIdx] ||
-        jsdocParameterNames[functionParameterIdx];
+      const matchedJsdoc = shallowJsdocParameterNames[functionParameterIdx - thisOffset] ||
+        jsdocParameterNames[functionParameterIdx - thisOffset];
 
       /** @type {string} */
       let rootName;
diff --git a/test/rules/assertions/requireParam.js b/test/rules/assertions/requireParam.js
index c8b6968a3..70c04cb7c 100644
--- a/test/rules/assertions/requireParam.js
+++ b/test/rules/assertions/requireParam.js
@@ -3640,5 +3640,22 @@ export default {
         },
       ],
     },
+    {
+      code: `
+        /**
+         * Returns the sum of two numbers
+         * @param options Object to destructure
+         * @param options.a First value
+         * @param options.b Second value
+         * @returns Sum of a and b
+         */
+        function sumDestructure(this: unknown, { a, b }: { a: number, b: number }) {
+          return a + b;
+        }
+      `,
+      languageOptions: {
+        parser: typescriptEslintParser,
+      },
+    },
   ],
 };