feat(require-param): add checkDestructuredRoots option; fixes #616

.README/rules/require-param.md

@@ -347,12 +347,24 @@ A value indicating whether getters should be checked. Defaults to `false`.
 
 Whether to require destructured properties. Defaults to `true`.
 
+##### `checkDestructuredRoots`
+
+Whether to check the existence of a corresponding `@param` for root objects
+of destructured properties (e.g., that for `function ({a, b}) {}`, that there
+is something like `@param myRootObj` defined that can correspond to
+the `{a, b}` object parameter).
+
+If `checkDestructuredRoots` is `false`, `checkDestructured` will also be
+implied to be `false` (i.e., the inside of the roots will not be checked
+either, e.g., it will also not complain if `a` or `b` do not have their own
+documentation). Defaults to `true`.
+
 |          |                                                                                                               |
 | -------- | ------------------------------------------------------------------------------------------------------------- |
 | Context  | `ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled |
 | Tags     | `param`                                                                                                       |
 | Aliases  | `arg`, `argument`                                                                                             |
-| Options  | `autoIncrementBase`, `checkDestructured`, `contexts`, `enableFixer`, `enableRootFixer`, `enableRestElementFixer`, `checkRestProperty`, `exemptedBy`, `checkConstructors`, `checkGetters`, `checkSetters`, `checkTypesPattern`, `unnamedRootBase`                                 |
+| Options  | `autoIncrementBase`, `checkDestructured`, `checkDestructuredRoots`, `contexts`, `enableFixer`, `enableRootFixer`, `enableRestElementFixer`, `checkRestProperty`, `exemptedBy`, `checkConstructors`, `checkGetters`, `checkSetters`, `checkTypesPattern`, `unnamedRootBase`                                 |
 | Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`                               |
 
 <!-- assertions requireParam -->

README.md

@@ -10666,12 +10666,25 @@ A value indicating whether getters should be checked. Defaults to `false`.
 
 Whether to require destructured properties. Defaults to `true`.
 
+<a name="eslint-plugin-jsdoc-rules-require-param-options-23-checkdestructuredroots"></a>
+##### <code>checkDestructuredRoots</code>
+
+Whether to check the existence of a corresponding `@param` for root objects
+of destructured properties (e.g., that for `function ({a, b}) {}`, that there
+is something like `@param myRootObj` defined that can correspond to
+the `{a, b}` object parameter).
+
+If `checkDestructuredRoots` is `false`, `checkDestructured` will also be
+implied to be `false` (i.e., the inside of the roots will not be checked
+either, e.g., it will also not complain if `a` or `b` do not have their own
+documentation). Defaults to `true`.
+
 |          |                                                                                                               |
 | -------- | ------------------------------------------------------------------------------------------------------------- |
 | Context  | `ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled |
 | Tags     | `param`                                                                                                       |
 | Aliases  | `arg`, `argument`                                                                                             |
-| Options  | `autoIncrementBase`, `checkDestructured`, `contexts`, `enableFixer`, `enableRootFixer`, `enableRestElementFixer`, `checkRestProperty`, `exemptedBy`, `checkConstructors`, `checkGetters`, `checkSetters`, `checkTypesPattern`, `unnamedRootBase`                                 |
+| Options  | `autoIncrementBase`, `checkDestructured`, `checkDestructuredRoots`, `contexts`, `enableFixer`, `enableRootFixer`, `enableRestElementFixer`, `checkRestProperty`, `exemptedBy`, `checkConstructors`, `checkGetters`, `checkSetters`, `checkTypesPattern`, `unnamedRootBase`                                 |
 | Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`                               |
 
 The following patterns are considered problems:
@@ -10711,6 +10724,15 @@ function quux (foo, bar, {baz}) {
 // Options: [{"checkDestructured":false}]
 // Message: Missing JSDoc @param "bar" declaration.
 
+/**
+ * @param foo
+ */
+function quux (foo, bar, {baz}) {
+
+}
+// Options: [{"checkDestructuredRoots":false}]
+// Message: Missing JSDoc @param "bar" declaration.
+
 /**
  *
  */
@@ -11808,6 +11830,15 @@ function quux (foo, bar, {baz}) {
 }
 // Options: [{"checkDestructured":false}]
 
+/**
+ * @param foo
+ * @param bar
+ */
+function quux (foo, bar, {baz}) {
+
+}
+// Options: [{"checkDestructuredRoots":false}]
+
 /**
  * @param root
  * @param root.foo

src/rules/requireParam.js

@@ -51,6 +51,7 @@ export default iterateJsdoc(({
     autoIncrementBase = 0,
     checkRestProperty = false,
     checkDestructured = true,
+    checkDestructuredRoots = true,
     checkTypesPattern = '/^(?:[oO]bject|[aA]rray|PlainObject|Generic(?:Object|Array))$/',
     enableFixer = true,
     enableRootFixer = true,
@@ -133,6 +134,10 @@ export default iterateJsdoc(({
         return;
       }
 
+      if (!checkDestructuredRoots) {
+        return;
+      }
+
       names.forEach((paramName, idx) => {
         // Add root if the root name is not in the docs (and is not already
         //  in the tags to be fixed)
@@ -274,6 +279,11 @@ export default iterateJsdoc(({
             type: 'boolean',
           },
           checkDestructured: {
+            default: true,
+            type: 'boolean',
+          },
+          checkDestructuredRoots: {
+            default: true,
             type: 'boolean',
           },
           checkGetters: {

test/rules/assertions/requireParam.js

@@ -117,6 +117,35 @@ export default {
           }
       `,
     },
+    {
+      code: `
+          /**
+           * @param foo
+           */
+          function quux (foo, bar, {baz}) {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc @param "bar" declaration.',
+        },
+      ],
+      options: [
+        {
+          checkDestructuredRoots: false,
+        },
+      ],
+      output: `
+          /**
+           * @param foo
+           * @param bar
+           */
+          function quux (foo, bar, {baz}) {
+
+          }
+      `,
+    },
     {
       code: `
           /**
@@ -2776,6 +2805,22 @@ export default {
         },
       ],
     },
+    {
+      code: `
+          /**
+           * @param foo
+           * @param bar
+           */
+          function quux (foo, bar, {baz}) {
+
+          }
+      `,
+      options: [
+        {
+          checkDestructuredRoots: false,
+        },
+      ],
+    },
     {
       code: `
           /**