diff --git a/.README/rules/require-param.md b/.README/rules/require-param.md
index f92310592..64d6bc590 100644
--- a/.README/rules/require-param.md
+++ b/.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` |
diff --git a/README.md b/README.md
index cd6ebce61..84e723164 100644
--- a/README.md
+++ b/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`.
+
+##### 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` |
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
diff --git a/src/rules/requireParam.js b/src/rules/requireParam.js
index ce47d8629..d20135767 100644
--- a/src/rules/requireParam.js
+++ b/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: {
diff --git a/test/rules/assertions/requireParam.js b/test/rules/assertions/requireParam.js
index 83103a6a4..52d38e702 100644
--- a/test/rules/assertions/requireParam.js
+++ b/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: `
/**