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: ` /**