fix(requireParam): update return type to include foundIndex and tagLineCount (#1531)

* fix(requireParam): update return type to include foundIndex and tagLineCount, fixes #1530

* test(requireParam): add test case for missing JSDoc @param declaration, #1530

* fix(require-param): add missing JSDoc @param declaration for new function example

* test: add test case which previously failed

* chore: update devDeps.

---------

Co-authored-by: Brett Zamir <brettz9@yahoo.com>

Author: mvarchdev

docs/rules/require-param.md

@@ -1265,6 +1265,35 @@ function quux ({
 }
 // "jsdoc/require-param": ["error"|"warn", {"interfaceExemptsParamsCheck":true}]
 // Message: Missing JSDoc @param "root0" declaration.
+
+/**
+ * @param foo
+ * @param baz
+ * @returns {number}
+ */
+function quux (foo, bar, baz) {
+  return foo + bar + baz;
+}
+// Message: Missing JSDoc @param "bar" declaration.
+
+/**
+ * @example
+ * ```ts
+ * app.use(checkResourceOwnership({ entryPoint: 'seller_product' }));
+ * ```
+ *
+ * @example
+ * ```ts
+ * app.use(checkResourceOwnership({ entryPoint: 'service_zone' }));
+ * ```
+ *
+ * @param options - configuration
+ * @param options.entryPoint
+ * @param options.filterField
+ * @param options.paramIdField
+ */
+export const checkResourceOwnership = ({ entryPoint, filterField, paramIdField, resourceId = () => '' }) => {};
+// Message: Missing JSDoc @param "options.resourceId" declaration.
 ````
 
 

package.json

@@ -5,7 +5,7 @@
     "url": "http://gajus.com"
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "~0.61.0",
+    "@es-joy/jsdoccomment": "~0.62.0",
     "are-docs-informative": "^0.0.2",
     "comment-parser": "1.4.1",
     "debug": "^4.4.3",
@@ -58,7 +58,7 @@
     "glob": "^11.0.3",
     "globals": "^16.4.0",
     "husky": "^9.1.7",
-    "jsdoc-type-pratt-parser": "^5.8.0",
+    "jsdoc-type-pratt-parser": "^5.9.0",
     "json-schema": "^0.4.0",
     "json-schema-to-typescript": "^15.0.4",
     "lint-staged": "^16.2.1",

pnpm-lock.yaml

@@ -175,7 +175,10 @@ export default iterateJsdoc(({
    *   newAdd?: boolean
    * })[]} jsdocTags
    * @param {import('../iterateJsdoc.js').Integer} indexAtFunctionParams
-   * @returns {import('../iterateJsdoc.js').Integer}
+   * @returns {{
+   *   foundIndex: import('../iterateJsdoc.js').Integer,
+   *   tagLineCount: import('../iterateJsdoc.js').Integer,
+   * }}
    */
   const findExpectedIndex = (jsdocTags, indexAtFunctionParams) => {
     const remainingRoots = functionParameterNames.slice(indexAtFunctionParams || 0);
@@ -225,7 +228,10 @@ export default iterateJsdoc(({
       }
     }
 
-    return tagLineCount;
+    return {
+      foundIndex,
+      tagLineCount,
+    };
   };
 
   let [
@@ -486,8 +492,22 @@ export default iterateJsdoc(({
     if (remove) {
       createTokens(functionParameterIdx, offset + functionParameterIdx, 1);
     } else {
-      const expectedIdx = findExpectedIndex(jsdoc.tags, functionParameterIdx);
-      createTokens(expectedIdx, offset + expectedIdx, 0);
+      const {
+        foundIndex,
+        tagLineCount: expectedIdx,
+      } =
+        findExpectedIndex(jsdoc.tags, functionParameterIdx);
+
+      const firstParamLine = jsdoc.source.findIndex(({
+        tokens,
+      }) => {
+        return tokens.tag === `@${preferredTagName}`;
+      });
+      const baseOffset = foundIndex > -1 || firstParamLine === -1 ?
+        offset :
+        firstParamLine;
+
+      createTokens(expectedIdx, baseOffset + expectedIdx, 0);
     }
   };
 

src/rules/requireParam.js

@@ -2668,6 +2668,82 @@ export default /** @type {import('../index.js').TestCases} */ ({
           }
       `,
     },
+    {
+      code: `
+          /**
+           * @param foo
+           * @param baz
+           * @returns {number}
+           */
+          function quux (foo, bar, baz) {
+            return foo + bar + baz;
+          }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @param "bar" declaration.',
+        },
+      ],
+      output: `
+          /**
+           * @param foo
+           * @param bar
+           * @param baz
+           * @returns {number}
+           */
+          function quux (foo, bar, baz) {
+            return foo + bar + baz;
+          }
+      `,
+    },
+    {
+      code: `
+        /**
+         * @example
+         * \`\`\`ts
+         * app.use(checkResourceOwnership({ entryPoint: 'seller_product' }));
+         * \`\`\`
+         *
+         * @example
+         * \`\`\`ts
+         * app.use(checkResourceOwnership({ entryPoint: 'service_zone' }));
+         * \`\`\`
+         *
+         * @param options - configuration
+         * @param options.entryPoint
+         * @param options.filterField
+         * @param options.paramIdField
+         */
+        export const checkResourceOwnership = ({ entryPoint, filterField, paramIdField, resourceId = () => '' }) => {};
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @param "options.resourceId" declaration.',
+        },
+      ],
+      output: `
+        /**
+         * @example
+         * \`\`\`ts
+         * app.use(checkResourceOwnership({ entryPoint: 'seller_product' }));
+         * \`\`\`
+         *
+         * @example
+         * \`\`\`ts
+         * app.use(checkResourceOwnership({ entryPoint: 'service_zone' }));
+         * \`\`\`
+         *
+         * @param options - configuration
+         * @param options.entryPoint
+         * @param options.filterField
+         * @param options.paramIdField
+         * @param options.resourceId
+         */
+        export const checkResourceOwnership = ({ entryPoint, filterField, paramIdField, resourceId = () => '' }) => {};
+      `,
+    },
   ],
   valid: [
     {