diff --git a/.README/rules/require-param.md b/.README/rules/require-param.md index 6fc67138..cf85459a 100644 --- a/.README/rules/require-param.md +++ b/.README/rules/require-param.md @@ -369,6 +369,11 @@ documentation). Defaults to `true`. Set to `true` if you wish to expect documentation of properties on objects supplied as default values. Defaults to `false`. +### `ignoreWhenAllParamsMissing` + +Set to `true` to ignore reporting when all params are missing. Defaults to +`false`. + ## Context and settings | | | @@ -377,7 +382,7 @@ supplied as default values. Defaults to `false`. | Tags | `param` | | Aliases | `arg`, `argument` | |Recommended | true| -| Options |`autoIncrementBase`, `checkConstructors`, `checkDestructured`, `checkDestructuredRoots`, `checkGetters`, `checkRestProperty`, `checkSetters`, `checkTypesPattern`, `contexts`, `enableFixer`, `enableRestElementFixer`, `enableRootFixer`, `exemptedBy`, `unnamedRootBase`, `useDefaultObjectProperties`| +| Options |`autoIncrementBase`, `checkConstructors`, `checkDestructured`, `checkDestructuredRoots`, `checkGetters`, `checkRestProperty`, `checkSetters`, `checkTypesPattern`, `contexts`, `enableFixer`, `enableRestElementFixer`, `enableRootFixer`, `exemptedBy`, `ignoreWhenAllParamsMissing`, `unnamedRootBase`, `useDefaultObjectProperties`| | Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`| ## Failing examples diff --git a/docs/rules/require-param.md b/docs/rules/require-param.md index fa600655..7e757b10 100644 --- a/docs/rules/require-param.md +++ b/docs/rules/require-param.md @@ -23,6 +23,7 @@ * [`checkDestructured`](#user-content-require-param-options-checkdestructured) * [`checkDestructuredRoots`](#user-content-require-param-options-checkdestructuredroots) * [`useDefaultObjectProperties`](#user-content-require-param-options-usedefaultobjectproperties) + * [`ignoreWhenAllParamsMissing`](#user-content-require-param-options-ignorewhenallparamsmissing) * [Context and settings](#user-content-require-param-context-and-settings) * [Failing examples](#user-content-require-param-failing-examples) * [Passing examples](#user-content-require-param-passing-examples) @@ -437,6 +438,13 @@ documentation). Defaults to `true`. Set to `true` if you wish to expect documentation of properties on objects supplied as default values. Defaults to `false`. + + +### ignoreWhenAllParamsMissing + +Set to `true` to ignore reporting when all params are missing. Defaults to +`false`. + ## Context and settings @@ -447,7 +455,7 @@ supplied as default values. Defaults to `false`. | Tags | `param` | | Aliases | `arg`, `argument` | |Recommended | true| -| Options |`autoIncrementBase`, `checkConstructors`, `checkDestructured`, `checkDestructuredRoots`, `checkGetters`, `checkRestProperty`, `checkSetters`, `checkTypesPattern`, `contexts`, `enableFixer`, `enableRestElementFixer`, `enableRootFixer`, `exemptedBy`, `unnamedRootBase`, `useDefaultObjectProperties`| +| Options |`autoIncrementBase`, `checkConstructors`, `checkDestructured`, `checkDestructuredRoots`, `checkGetters`, `checkRestProperty`, `checkSetters`, `checkTypesPattern`, `contexts`, `enableFixer`, `enableRestElementFixer`, `enableRootFixer`, `exemptedBy`, `ignoreWhenAllParamsMissing`, `unnamedRootBase`, `useDefaultObjectProperties`| | Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`| @@ -1162,6 +1170,14 @@ class A { } } // Message: Missing JSDoc @param "root1" declaration. + +/** + * Some desc. + * @param a + */ +function quux (a, b) {} +// "jsdoc/require-param": ["error"|"warn", {"ignoreWhenAllParamsMissing":true}] +// Message: Missing JSDoc @param "b" declaration. ```` @@ -1813,5 +1829,11 @@ const inner = (c: number, d: string): void => { console.log(d); }; // Settings: {"jsdoc":{"contexts":["VariableDeclaration"]}} + +/** + * Some desc. + */ +function quux (a, b) {} +// "jsdoc/require-param": ["error"|"warn", {"ignoreWhenAllParamsMissing":true}] ```` diff --git a/src/rules/requireParam.js b/src/rules/requireParam.js index 33f50db7..28e0b66e 100644 --- a/src/rules/requireParam.js +++ b/src/rules/requireParam.js @@ -60,6 +60,7 @@ export default iterateJsdoc(({ 'root', ], useDefaultObjectProperties = false, + ignoreWhenAllParamsMissing = false, } = context.options[0] || {}; const preferredTagName = /** @type {string} */ (utils.getPreferredTagName({ @@ -83,6 +84,10 @@ export default iterateJsdoc(({ * }[]} */ (utils.getJsdocTagsDeep(preferredTagName)); + if (ignoreWhenAllParamsMissing && !jsdocParameterNames.length) { + return; + } + const shallowJsdocParameterNames = jsdocParameterNames.filter((tag) => { return !tag.name.includes('.'); }).map((tag, idx) => { @@ -571,6 +576,9 @@ export default iterateJsdoc(({ }, type: 'array', }, + ignoreWhenAllParamsMissing: { + type: 'boolean', + }, unnamedRootBase: { items: { type: 'string', diff --git a/test/rules/assertions/requireParam.js b/test/rules/assertions/requireParam.js index 666cb4ab..71f8c32d 100644 --- a/test/rules/assertions/requireParam.js +++ b/test/rules/assertions/requireParam.js @@ -2527,6 +2527,33 @@ export default { } `, }, + { + code: ` + /** + * Some desc. + * @param a + */ + function quux (a, b) {} + `, + errors: [ + { + message: 'Missing JSDoc @param "b" declaration.', + }, + ], + options: [ + { + ignoreWhenAllParamsMissing: true, + } + ], + output: ` + /** + * Some desc. + * @param a + * @param b + */ + function quux (a, b) {} + `, + }, ], valid: [ { @@ -3604,5 +3631,18 @@ export default { } }, }, + { + code: ` + /** + * Some desc. + */ + function quux (a, b) {} + `, + options: [ + { + ignoreWhenAllParamsMissing: true, + } + ], + }, ], };