@depup/eslint-plugin-jsdoc 64.0.2-depup.1 → 64.2.0-depup.0

package/README.md

@@ -13,16 +13,10 @@ npm install @depup/eslint-plugin-jsdoc
 
 | Field | Value |
 |-------|-------|
-| Original | [eslint-plugin-jsdoc](https://www.npmjs.com/package/eslint-plugin-jsdoc) @ 64.0.2 |
-| Processed | 2026-08-10 |
+| Original | [eslint-plugin-jsdoc](https://www.npmjs.com/package/eslint-plugin-jsdoc) @ 64.2.0 |
+| Processed | 2026-08-15 |
 | Smoke test | passed |
-| Deps updated | 1 |
-
-## Dependency Changes
-
-| Dependency | From | To |
-|------------|------|-----|
-| @es-joy/jsdoccomment | ~0.93.2 | ^0.94.0 |
+| Deps updated | 0 |
 
 ---
 

package/changes.json

@@ -1,10 +1,5 @@
 {
-  "bumped": {
-    "@es-joy/jsdoccomment": {
-      "from": "~0.93.2",
-      "to": "^0.94.0"
-    }
-  },
-  "timestamp": "2026-08-10T00:23:14.163Z",
-  "totalUpdated": 1
+  "bumped": {},
+  "timestamp": "2026-08-15T08:06:56.049Z",
+  "totalUpdated": 0
 }

package/dist/iterateJsdoc.d.ts

@@ -52,12 +52,16 @@ export type BasicUtils = {
 export type IsIteratingFunction = () => boolean;
 export type IsVirtualFunction = () => boolean;
 export type Stringify = (tagBlock: import("comment-parser").Block, specRewire?: boolean | undefined) => string;
+export type JsdocSuggestions = {
+    desc: string;
+    handler: (fixer: import("eslint").Rule.RuleFixer) => import("eslint").Rule.Fix | void;
+}[];
 export type ReportJSDoc = (msg: string, tag?: import("comment-parser").Spec | {
     line: Integer;
     column?: Integer;
 } | null | undefined, handler?: ((fixer: import("eslint").Rule.RuleFixer) => import("eslint").Rule.Fix | void) | null | undefined, specRewire?: boolean | undefined, data?: undefined | {
     [key: string]: string;
-}) => any;
+}, suggestions?: JsdocSuggestions | undefined) => any;
 export type GetRegexFromString = (str: string, requiredFlags?: string | undefined) => RegExp;
 export type GetTagDescription = (tg: import("comment-parser").Spec, returnArray?: boolean | undefined) => string[] | string;
 export type SetTagDescription = (tg: import("comment-parser").Spec, matcher: RegExp, setter: (description: string) => string) => Integer;
@@ -256,7 +260,7 @@ export type Report = (message: string, fix?: import("@eslint/core").RuleFixer |
     line?: Integer;
 }) | null | undefined, data?: undefined | {
     [key: string]: string;
-}) => void;
+}, suggest?: import("eslint").Rule.SuggestionReportDescriptor[] | undefined) => void;
 export type PreferredTypes = {
     [key: string]: false | string | {
         message: string;

package/dist/rules.d.ts

@@ -143,6 +143,16 @@ export interface Rules {
            * `@param`'s and present function parameters will still be reported.
            */
           allowExtraTrailingParamDocs?: boolean;
+          /**
+           * Whether to offer a suggestion to rename a mismatched `@param` to the
+           * corresponding function parameter name. Defaults to `false`.
+           */
+          badParamNames?: boolean;
+          /**
+           * Whether to report `@param` definitions whose names match the function
+           * parameters but appear in a different order. Defaults to `true`.
+           */
+          badParamOrder?: boolean;
           /**
            * Whether to check destructured properties. Defaults to `true`.
            */
@@ -206,14 +216,23 @@ export interface Rules {
            */
           disableMissingParamChecks?: boolean;
           /**
-           * Set to `true` to auto-remove `@param` duplicates (based on identical
-           * names).
+           * Whether to report duplicate `@param` definitions. Defaults to `true`.
+           */
+          duplicateParams?: boolean;
+          /**
+           * Set to `true` to reorder non-nested `@param` definitions to match the
+           * function signature and to auto-remove duplicates (based on identical names).
            *
            * Note that this option will remove duplicates of the same name even if
            * the definitions do not match in other ways (e.g., the second param will
            * be removed even if it has a different type or description).
            */
           enableFixer?: boolean;
+          /**
+           * Whether to offer a suggestion to remove an `@param` that has no
+           * corresponding function parameter. Defaults to `false`.
+           */
+          extraParams?: boolean;
           /**
            * Set to `true` if you wish to avoid reporting of child property documentation
            * where instead of destructuring, a whole plain object is supplied as default

package/package.json

@@ -5,7 +5,7 @@
     "url": "http://gajus.com"
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "^0.94.0",
+    "@es-joy/jsdoccomment": "~0.95.0",
     "@es-joy/resolve.exports": "1.2.0",
     "are-docs-informative": "^0.1.1",
     "comment-parser": "1.4.8",
@@ -43,7 +43,7 @@
     "@types/node": "^26.2.0",
     "@types/semver": "^7.8.0",
     "@types/spdx-expression-parse": "^4.0.0",
-    "@typescript-eslint/types": "8.66.0",
+    "@typescript-eslint/types": "8.67.0",
     "babel-plugin-add-module-exports": "^1.0.4",
     "babel-plugin-transform-import-meta": "^3.0.0",
     "c8": "^12.0.0",
@@ -56,7 +56,7 @@
     "glob": "^13.0.6",
     "globals": "^17.9.0",
     "husky": "^9.1.7",
-    "jsdoc-type-pratt-parser": "^9.0.1",
+    "jsdoc-type-pratt-parser": "^9.1.1",
     "json-schema": "^0.4.0",
     "json-schema-to-typescript": "^15.0.4",
     "lint-staged": "^17.3.0",
@@ -69,7 +69,7 @@
     "sinon": "^22.1.0",
     "ts-api-utils": "^2.5.0",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.66.0"
+    "typescript-eslint": "8.67.0"
   },
   "engines": {
     "node": "^22.22.2 || >=24.15.0"
@@ -160,18 +160,13 @@
     "test-cov": "TIMING=1 c8 --reporter text pnpm run test-no-cov",
     "test-index": "pnpm run test-no-cov test/rules/index.js"
   },
-  "version": "64.0.2-depup.1",
+  "version": "64.2.0-depup.0",
   "depup": {
-    "changes": {
-      "@es-joy/jsdoccomment": {
-        "from": "~0.93.2",
-        "to": "^0.94.0"
-      }
-    },
-    "depsUpdated": 1,
+    "changes": {},
+    "depsUpdated": 0,
     "originalPackage": "eslint-plugin-jsdoc",
-    "originalVersion": "64.0.2",
-    "processedAt": "2026-08-10T00:23:37.482Z",
+    "originalVersion": "64.2.0",
+    "processedAt": "2026-08-15T08:07:17.964Z",
     "smokeTest": "passed"
   }
 }

package/src/iterateJsdoc.js

@@ -117,6 +117,13 @@ import esquery from 'esquery';
  * @returns {string}
  */
 
+/**
+ * @typedef {{
+ *   desc: string,
+ *   handler: (fixer: import('eslint').Rule.RuleFixer) => import('eslint').Rule.Fix|void
+ * }[]} JsdocSuggestions
+ */
+
 /**
  * @callback ReportJSDoc
  * @param {string} msg
@@ -126,6 +133,7 @@ import esquery from 'esquery';
  * @param {undefined|{
  *   [key: string]: string
  * }} [data]
+ * @param {JsdocSuggestions} [suggestions]
  */
 
 /**
@@ -698,6 +706,7 @@ const getBasicUtils = (context, {
  * @param {undefined|{
  *   [key: string]: string
  * }} [data]
+ * @param {import('eslint').Rule.SuggestionReportDescriptor[]} [suggest]
  * @returns {void}
  */
 
@@ -808,24 +817,42 @@ const getUtils = (
   };
 
   /** @type {ReportJSDoc} */
-  utils.reportJSDoc = (msg, tag, handler, specRewire, data) => {
-    report(msg, handler ? /** @type {import('eslint').Rule.ReportFixer} */ (
-      fixer,
-    ) => {
-      const extraFix = handler(fixer);
-
-      const replacement = utils.stringify(jsdoc, specRewire);
-
-      if (!replacement) {
-        const text = sourceCode.getText();
-        const lastLineBreakPos = text.slice(
-          0, jsdocNode.range[0],
-        ).search(/\n[ \t]*$/v);
-        if (lastLineBreakPos > -1) {
+  utils.reportJSDoc = (msg, tag, handler, specRewire, data, suggestions) => {
+    /**
+     * @param {(fixer: import('eslint').Rule.RuleFixer) => import('eslint').Rule.Fix|void} fixHandler
+     * @returns {import('eslint').Rule.ReportFixer}
+     */
+    const makeFix = (fixHandler) => {
+      return (fixer) => {
+        const extraFix = fixHandler(fixer);
+
+        const replacement = utils.stringify(jsdoc, specRewire);
+
+        if (!replacement) {
+          const text = sourceCode.getText();
+          const lastLineBreakPos = text.slice(
+            0, jsdocNode.range[0],
+          ).search(/\n[ \t]*$/v);
+          if (lastLineBreakPos > -1) {
+            return [
+              fixer.removeRange([
+                lastLineBreakPos, jsdocNode.range[1],
+              ]),
+              /* c8 ignore next 2 -- Guard */
+              ...(extraFix ? [
+                extraFix,
+              ] : []),
+            ];
+          }
+
           return [
-            fixer.removeRange([
-              lastLineBreakPos, jsdocNode.range[1],
-            ]),
+            fixer.removeRange(
+              (/\s/v).test(text.charAt(jsdocNode.range[1])) ?
+                [
+                  jsdocNode.range[0], jsdocNode.range[1] + 1,
+                ] :
+                jsdocNode.range,
+            ),
             /* c8 ignore next 2 -- Guard */
             ...(extraFix ? [
               extraFix,
@@ -834,27 +861,29 @@ const getUtils = (
         }
 
         return [
-          fixer.removeRange(
-            (/\s/v).test(text.charAt(jsdocNode.range[1])) ?
-              [
-                jsdocNode.range[0], jsdocNode.range[1] + 1,
-              ] :
-              jsdocNode.range,
-          ),
-          /* c8 ignore next 2 -- Guard */
+          fixer.replaceText(jsdocNode, replacement),
           ...(extraFix ? [
             extraFix,
           ] : []),
         ];
-      }
+      };
+    };
 
-      return [
-        fixer.replaceText(jsdocNode, replacement),
-        ...(extraFix ? [
-          extraFix,
-        ] : []),
-      ];
-    } : null, tag, data);
+    report(
+      msg,
+      handler ? makeFix(handler) : null,
+      tag,
+      data,
+      suggestions?.map(({
+        desc,
+        handler: suggestionHandler,
+      }) => {
+        return {
+          desc,
+          fix: makeFix(suggestionHandler),
+        };
+      }),
+    );
   };
 
   /** @type {GetRegexFromString} */
@@ -1911,7 +1940,9 @@ const getSettings = (context) => {
 /** @type {MakeReport} */
 const makeReport = (context, commentNode) => {
   /** @type {Report} */
-  const report = (message, fix = null, jsdocLoc = null, data = undefined) => {
+  const report = (
+    message, fix = null, jsdocLoc = null, data = undefined, suggest = undefined,
+  ) => {
     let loc;
 
     if (jsdocLoc) {
@@ -1953,6 +1984,7 @@ const makeReport = (context, commentNode) => {
       loc,
       message,
       node: commentNode,
+      suggest,
     });
   };
 

package/src/rules/checkParamNames.js

@@ -1,14 +1,107 @@
 import iterateJsdoc from '../iterateJsdoc.js';
 
+/**
+ * @param {import('../jsdocUtils.js').ParamNameInfo} parameter
+ * @returns {string|undefined}
+ */
+const getSimpleParameterName = (parameter) => {
+  if (typeof parameter === 'string') {
+    return parameter;
+  }
+
+  if (
+    !parameter ||
+    Array.isArray(parameter) ||
+    typeof parameter !== 'object' ||
+    !('name' in parameter) ||
+    typeof parameter.name !== 'string'
+  ) {
+    return undefined;
+  }
+
+  return parameter.name;
+};
+
+/**
+ * @param {import('../iterateJsdoc.js').Integer} firstChangedTagIndex
+ * @param {import('comment-parser').Spec[]} orderedTags
+ * @param {import('comment-parser').Block} jsdoc
+ * @param {import('../iterateJsdoc.js').Utils} utils
+ * @returns {() => void}
+ */
+const makeParamOrderFix = (
+  firstChangedTagIndex, orderedTags, jsdoc, utils,
+) => {
+  return () => {
+    const itemsToMoveRange = [
+      ...Array.from({
+        length: jsdoc.tags.length - firstChangedTagIndex,
+      }).keys(),
+    ];
+
+    const unchangedPriorTagDescriptions = jsdoc.tags.slice(
+      0,
+      firstChangedTagIndex,
+    ).reduce((count, {
+      source,
+    }) => {
+      return count + source.length - 1;
+    }, 0);
+
+    const initialOffset =
+      /** @type {import('../iterateJsdoc.js').Integer} */ (utils.getFirstLine()) +
+      firstChangedTagIndex + unchangedPriorTagDescriptions;
+
+    for (const index of itemsToMoveRange) {
+      utils.removeTag(index + firstChangedTagIndex);
+    }
+
+    const changedTags = orderedTags.slice(firstChangedTagIndex);
+    let extraTagCount = 0;
+
+    for (const index of itemsToMoveRange) {
+      const changedTag = changedTags[index];
+
+      utils.addTag(
+        changedTag.tag,
+        extraTagCount + initialOffset + index,
+        {
+          ...changedTag.source[0].tokens,
+          end: '',
+        },
+      );
+
+      for (const {
+        tokens,
+      } of changedTag.source.slice(1)) {
+        if (!tokens.end) {
+          utils.addLine(
+            extraTagCount + initialOffset + index + 1,
+            {
+              ...tokens,
+              end: '',
+            },
+          );
+          extraTagCount++;
+        }
+      }
+    }
+  };
+};
+
 /**
  * @param {string} targetTagName
  * @param {boolean} allowExtraTrailingParamDocs
+ * @param {boolean} badParamNames
+ * @param {boolean} badParamOrder
  * @param {boolean} checkDestructured
  * @param {boolean} checkRestProperty
  * @param {RegExp} checkTypesRegex
  * @param {boolean} disableExtraPropertyReporting
  * @param {boolean} disableMissingParamChecks
+ * @param {boolean} duplicateParams
  * @param {boolean} enableFixer
+ * @param {boolean} extraParams
  * @param {import('../jsdocUtils.js').ParamNameInfo[]} functionParameterNames
  * @param {import('comment-parser').Block} jsdoc
  * @param {import('../iterateJsdoc.js').Utils} utils
@@ -18,12 +111,16 @@ import iterateJsdoc from '../iterateJsdoc.js';
 const validateParameterNames = (
   targetTagName,
   allowExtraTrailingParamDocs,
+  badParamNames,
+  badParamOrder,
   checkDestructured,
   checkRestProperty,
   checkTypesRegex,
   disableExtraPropertyReporting,
   disableMissingParamChecks,
+  duplicateParams,
   enableFixer,
+  extraParams,
   functionParameterNames, jsdoc, utils, report,
 ) => {
   const paramTags = Object.entries(jsdoc.tags).filter(([
@@ -36,12 +133,39 @@ const validateParameterNames = (
   ]) => {
     return !tag.name.includes('.');
   });
+  const actualParamNames = paramTagsNonNested.map(([
+    , tag,
+  ]) => {
+    return tag.name.trim();
+  });
+  const documentsThis = actualParamNames.includes('this');
+  const simpleFunctionParameterNames = functionParameterNames.filter((parameter) => {
+    return documentsThis || parameter !== 'this';
+  }).map(getSimpleParameterName);
+  const hasOnlySimpleParameterNames = simpleFunctionParameterNames.every((name) => {
+    return name !== undefined;
+  });
+  const expectedParamNames = /** @type {string[]} */ (simpleFunctionParameterNames);
+  const sortedActualParamNames = actualParamNames.toSorted();
+  const sortedExpectedParamNames = expectedParamNames.toSorted();
+  const sameParamNames = hasOnlySimpleParameterNames &&
+    actualParamNames.length === expectedParamNames.length &&
+    sortedActualParamNames.every((name, index) => {
+      return name === sortedExpectedParamNames[index];
+    });
+  const isBadParamOrder = sameParamNames && actualParamNames.some((name, index) => {
+    return name !== expectedParamNames[index];
+  });
+  const canFixParamOrder =
+    paramTags.length === paramTagsNonNested.length &&
+    new Set(actualParamNames).size === actualParamNames.length;
 
   let dotted = 0;
   let thisOffset = 0;
 
   return paramTags.some(([
-    , tag,
+    ,
+    tag,
   // eslint-disable-next-line complexity
   ], index) => {
     /** @type {import('../iterateJsdoc.js').Integer} */
@@ -54,7 +178,7 @@ const validateParameterNames = (
 
       return tg.name === tag.name && idx !== index;
     });
-    if (dupeTagInfo) {
+    if (dupeTagInfo && duplicateParams) {
       utils.reportJSDoc(`Duplicate @${targetTagName} "${tag.name}"`, dupeTagInfo[1], enableFixer ? () => {
         utils.removeTag(tagsIndex);
       } : null);
@@ -62,6 +186,14 @@ const validateParameterNames = (
       return true;
     }
 
+    if (!duplicateParams && paramTags.some(([
+      , earlierTag,
+    ], earlierIndex) => {
+      return earlierIndex < index && earlierTag.name === tag.name;
+    })) {
+      return false;
+    }
+
     if (tag.name.includes('.')) {
       dotted++;
 
@@ -69,7 +201,7 @@ const validateParameterNames = (
     }
 
     let functionParameterName = functionParameterNames[index - dotted + thisOffset];
-    if (functionParameterName === 'this' && tag.name.trim() !== 'this') {
+    if (!documentsThis && functionParameterName === 'this' && tag.name.trim() !== 'this') {
       ++thisOffset;
       functionParameterName = functionParameterNames[index - dotted + thisOffset];
     }
@@ -79,10 +211,25 @@ const validateParameterNames = (
         return false;
       }
 
-      report(
+      const removeExtraParam = () => {
+        const currentTagIndex = jsdoc.tags.indexOf(tag);
+        if (currentTagIndex !== -1) {
+          utils.removeTag(currentTagIndex);
+        }
+      };
+
+      utils.reportJSDoc(
         `@${targetTagName} "${tag.name}" does not match an existing function parameter.`,
-        null,
         tag,
+        extraParams ? removeExtraParam : null,
+        false,
+        undefined,
+        [
+          {
+            desc: `Remove the extra @${targetTagName} "${tag.name}".`,
+            handler: removeExtraParam,
+          },
+        ],
       );
 
       return true;
@@ -267,8 +414,59 @@ const validateParameterNames = (
 
         return item;
       }).filter((item) => {
-        return item !== 'this';
+        return documentsThis || item !== 'this';
       });
+      const message = `Expected @${targetTagName} names to be "${
+        expectedNames.map((expectedName) => {
+          return typeof expectedName === 'object' &&
+            'name' in expectedName &&
+            expectedName.restElement ?
+            '...' + expectedName.name :
+            expectedName;
+        }).join(', ')
+      }". Got "${actualNames.join(', ')}".`;
+
+      if (isBadParamOrder) {
+        if (!badParamOrder) {
+          return false;
+        }
+
+        let orderFix = null;
+        if (enableFixer && canFixParamOrder) {
+          const orderedTags =
+            /** @type {import('comment-parser').Spec[]} */ (
+              JSON.parse(JSON.stringify(jsdoc.tags))
+            );
+          for (const [
+            paramIndex,
+            expectedName,
+          ] of expectedParamNames.entries()) {
+            const matchingTag = /** @type {[string, import('comment-parser').Spec]} */ (
+              paramTagsNonNested.find(([
+                , candidateTag,
+              ]) => {
+                return candidateTag.name.trim() === expectedName;
+              })
+            );
+            orderedTags[Number(paramTagsNonNested[paramIndex][0])] =
+              JSON.parse(JSON.stringify(matchingTag[1]));
+          }
+
+          const firstChangedParamIndex = actualParamNames.findIndex((name, paramIndex) => {
+            return name !== expectedParamNames[paramIndex];
+          });
+          orderFix = makeParamOrderFix(
+            Number(paramTagsNonNested[firstChangedParamIndex][0]),
+            orderedTags,
+            jsdoc,
+            utils,
+          );
+        }
+
+        utils.reportJSDoc(message, tag, orderFix, true);
+
+        return true;
+      }
 
       // When disableMissingParamChecks is true tag names can be omitted.
       // Report when the tag names do not match the expected names or they are used out of order.
@@ -286,18 +484,22 @@ const validateParameterNames = (
         }
       }
 
-      report(
-        `Expected @${targetTagName} names to be "${
-          expectedNames.map((expectedName) => {
-            return typeof expectedName === 'object' &&
-              'name' in expectedName &&
-              expectedName.restElement ?
-              '...' + expectedName.name :
-              expectedName;
-          }).join(', ')
-        }". Got "${actualNames.join(', ')}".`,
-        null,
+      const renameBadParam = () => {
+        tag.source[0].tokens.name = String(funcParamName);
+      };
+
+      utils.reportJSDoc(
+        message,
         tag,
+        badParamNames ? renameBadParam : null,
+        true,
+        undefined,
+        [
+          {
+            desc: `Rename @${targetTagName} "${tag.name.trim()}" to "${funcParamName}".`,
+            handler: renameBadParam,
+          },
+        ],
       );
 
       return true;
@@ -377,12 +579,16 @@ export default iterateJsdoc(({
 }) => {
   const {
     allowExtraTrailingParamDocs,
+    badParamNames = false,
+    badParamOrder = true,
     checkDestructured = true,
     checkRestProperty = false,
     checkTypesPattern = '/^(?:[oO]bject|[aA]rray|PlainObject|Generic(?:Object|Array))$/',
     disableExtraPropertyReporting = false,
     disableMissingParamChecks = false,
+    duplicateParams = true,
     enableFixer = false,
+    extraParams = false,
     useDefaultObjectProperties = false,
   } = context.options[0] || {};
 
@@ -416,12 +622,16 @@ export default iterateJsdoc(({
   const isError = validateParameterNames(
     targetTagName,
     allowExtraTrailingParamDocs,
+    badParamNames,
+    badParamOrder,
     checkDestructured,
     checkRestProperty,
     checkTypesRegex,
     disableExtraPropertyReporting,
     disableMissingParamChecks,
+    duplicateParams,
     enableFixer,
+    extraParams,
     functionParameterNames,
     jsdoc,
     utils,
@@ -443,6 +653,7 @@ export default iterateJsdoc(({
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-param-names.md#repos-sticky-header',
     },
     fixable: 'code',
+    hasSuggestions: true,
     schema: [
       {
         additionalProperties: false,
@@ -454,6 +665,16 @@ their presence within the function signature. Other inconsistencies between
 \`@param\`'s and present function parameters will still be reported.`,
             type: 'boolean',
           },
+          badParamNames: {
+            description: `Whether to auto-fix a mismatched \`@param\` name to the corresponding
+function parameter name. A suggestion is always offered. Defaults to \`false\`.`,
+            type: 'boolean',
+          },
+          badParamOrder: {
+            description: `Whether to report \`@param\` definitions whose names match the function
+parameters but appear in a different order. Defaults to \`true\`.`,
+            type: 'boolean',
+          },
           checkDestructured: {
             description: 'Whether to check destructured properties. Defaults to `true`.',
             type: 'boolean',
@@ -516,15 +737,24 @@ that are available and actually used in the function.`,
             description: 'Whether to avoid checks for missing `@param` definitions. Defaults to `false`. Change to `true` if you want to be able to omit properties.',
             type: 'boolean',
           },
+          duplicateParams: {
+            description: 'Whether to report duplicate `@param` definitions. Defaults to `true`.',
+            type: 'boolean',
+          },
           enableFixer: {
-            description: `Set to \`true\` to auto-remove \`@param\` duplicates (based on identical
-names).
+            description: `Set to \`true\` to reorder non-nested \`@param\` definitions to match the
+function signature and to auto-remove duplicates (based on identical names).
 
 Note that this option will remove duplicates of the same name even if
 the definitions do not match in other ways (e.g., the second param will
 be removed even if it has a different type or description).`,
             type: 'boolean',
           },
+          extraParams: {
+            description: `Whether to auto-remove an \`@param\` that has no corresponding function
+parameter. A suggestion is always offered. Defaults to \`false\`.`,
+            type: 'boolean',
+          },
           useDefaultObjectProperties: {
             description: `Set to \`true\` if you wish to avoid reporting of child property documentation
 where instead of destructuring, a whole plain object is supplied as default

package/src/rules.d.ts

@@ -143,6 +143,16 @@ export interface Rules {
            * `@param`'s and present function parameters will still be reported.
            */
           allowExtraTrailingParamDocs?: boolean;
+          /**
+           * Whether to offer a suggestion to rename a mismatched `@param` to the
+           * corresponding function parameter name. Defaults to `false`.
+           */
+          badParamNames?: boolean;
+          /**
+           * Whether to report `@param` definitions whose names match the function
+           * parameters but appear in a different order. Defaults to `true`.
+           */
+          badParamOrder?: boolean;
           /**
            * Whether to check destructured properties. Defaults to `true`.
            */
@@ -206,14 +216,23 @@ export interface Rules {
            */
           disableMissingParamChecks?: boolean;
           /**
-           * Set to `true` to auto-remove `@param` duplicates (based on identical
-           * names).
+           * Whether to report duplicate `@param` definitions. Defaults to `true`.
+           */
+          duplicateParams?: boolean;
+          /**
+           * Set to `true` to reorder non-nested `@param` definitions to match the
+           * function signature and to auto-remove duplicates (based on identical names).
            *
            * Note that this option will remove duplicates of the same name even if
            * the definitions do not match in other ways (e.g., the second param will
            * be removed even if it has a different type or description).
            */
           enableFixer?: boolean;
+          /**
+           * Whether to offer a suggestion to remove an `@param` that has no
+           * corresponding function parameter. Defaults to `false`.
+           */
+          extraParams?: boolean;
           /**
            * Set to `true` if you wish to avoid reporting of child property documentation
            * where instead of destructuring, a whole plain object is supplied as default