Skip to content

Commit 3b18435

Browse files
brettz9brettz9
committed
feat(require-param): add ignoreWhenAllParamsMissing option; fixes #1317 
1 parent 51c68b1 commit 3b18435

4 files changed

Lines changed: 77 additions & 2 deletions

File tree

‎.README/rules/require-param.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -369,6 +369,11 @@ documentation). Defaults to `true`.
369369
Set to `true` if you wish to expect documentation of properties on objects
370370
supplied as default values. Defaults to `false`.
371371

372+
### `ignoreWhenAllParamsMissing`
373+
374+
Set to `true` to ignore reporting when all params are missing. Defaults to
375+
`false`.
376+
372377
## Context and settings
373378

374379
| | |
@@ -377,7 +382,7 @@ supplied as default values. Defaults to `false`.
377382
| Tags | `param` |
378383
| Aliases | `arg`, `argument` |
379384
|Recommended | true|
380-
| Options |`autoIncrementBase`, `checkConstructors`, `checkDestructured`, `checkDestructuredRoots`, `checkGetters`, `checkRestProperty`, `checkSetters`, `checkTypesPattern`, `contexts`, `enableFixer`, `enableRestElementFixer`, `enableRootFixer`, `exemptedBy`, `unnamedRootBase`, `useDefaultObjectProperties`|
385+
| Options |`autoIncrementBase`, `checkConstructors`, `checkDestructured`, `checkDestructuredRoots`, `checkGetters`, `checkRestProperty`, `checkSetters`, `checkTypesPattern`, `contexts`, `enableFixer`, `enableRestElementFixer`, `enableRootFixer`, `exemptedBy`, `ignoreWhenAllParamsMissing`, `unnamedRootBase`, `useDefaultObjectProperties`|
381386
| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
382387

383388
## Failing examples

‎docs/rules/require-param.md‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
* [`checkDestructured`](#user-content-require-param-options-checkdestructured)
2424
* [`checkDestructuredRoots`](#user-content-require-param-options-checkdestructuredroots)
2525
* [`useDefaultObjectProperties`](#user-content-require-param-options-usedefaultobjectproperties)
26+
* [`ignoreWhenAllParamsMissing`](#user-content-require-param-options-ignorewhenallparamsmissing)
2627
* [Context and settings](#user-content-require-param-context-and-settings)
2728
* [Failing examples](#user-content-require-param-failing-examples)
2829
* [Passing examples](#user-content-require-param-passing-examples)
@@ -437,6 +438,13 @@ documentation). Defaults to `true`.
437438
Set to `true` if you wish to expect documentation of properties on objects
438439
supplied as default values. Defaults to `false`.
439440

441+
<a name="user-content-require-param-options-ignorewhenallparamsmissing"></a>
442+
<a name="require-param-options-ignorewhenallparamsmissing"></a>
443+
### <code>ignoreWhenAllParamsMissing</code>
444+
445+
Set to `true` to ignore reporting when all params are missing. Defaults to
446+
`false`.
447+
440448
<a name="user-content-require-param-context-and-settings"></a>
441449
<a name="require-param-context-and-settings"></a>
442450
## Context and settings
@@ -447,7 +455,7 @@ supplied as default values. Defaults to `false`.
447455
| Tags | `param` |
448456
| Aliases | `arg`, `argument` |
449457
|Recommended | true|
450-
| Options |`autoIncrementBase`, `checkConstructors`, `checkDestructured`, `checkDestructuredRoots`, `checkGetters`, `checkRestProperty`, `checkSetters`, `checkTypesPattern`, `contexts`, `enableFixer`, `enableRestElementFixer`, `enableRootFixer`, `exemptedBy`, `unnamedRootBase`, `useDefaultObjectProperties`|
458+
| Options |`autoIncrementBase`, `checkConstructors`, `checkDestructured`, `checkDestructuredRoots`, `checkGetters`, `checkRestProperty`, `checkSetters`, `checkTypesPattern`, `contexts`, `enableFixer`, `enableRestElementFixer`, `enableRootFixer`, `exemptedBy`, `ignoreWhenAllParamsMissing`, `unnamedRootBase`, `useDefaultObjectProperties`|
451459
| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
452460

453461
<a name="user-content-require-param-failing-examples"></a>
@@ -1162,6 +1170,14 @@ class A {
11621170
}
11631171
}
11641172
// Message: Missing JSDoc @param "root1" declaration.
1173+
1174+
/**
1175+
* Some desc.
1176+
* @param a
1177+
*/
1178+
function quux (a, b) {}
1179+
// "jsdoc/require-param": ["error"|"warn", {"ignoreWhenAllParamsMissing":true}]
1180+
// Message: Missing JSDoc @param "b" declaration.
11651181
````
11661182

11671183

@@ -1813,5 +1829,11 @@ const inner = (c: number, d: string): void => {
18131829
console.log(d);
18141830
};
18151831
// Settings: {"jsdoc":{"contexts":["VariableDeclaration"]}}
1832+
1833+
/**
1834+
* Some desc.
1835+
*/
1836+
function quux (a, b) {}
1837+
// "jsdoc/require-param": ["error"|"warn", {"ignoreWhenAllParamsMissing":true}]
18161838
````
18171839

‎src/rules/requireParam.js‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ export default iterateJsdoc(({
6060
'root',
6161
],
6262
useDefaultObjectProperties = false,
63+
ignoreWhenAllParamsMissing = false,
6364
} = context.options[0] || {};
6465

6566
const preferredTagName = /** @type {string} */ (utils.getPreferredTagName({
@@ -83,6 +84,10 @@ export default iterateJsdoc(({
8384
* }[]}
8485
*/ (utils.getJsdocTagsDeep(preferredTagName));
8586

87+
if (ignoreWhenAllParamsMissing && !jsdocParameterNames.length) {
88+
return;
89+
}
90+
8691
const shallowJsdocParameterNames = jsdocParameterNames.filter((tag) => {
8792
return !tag.name.includes('.');
8893
}).map((tag, idx) => {
@@ -571,6 +576,9 @@ export default iterateJsdoc(({
571576
},
572577
type: 'array',
573578
},
579+
ignoreWhenAllParamsMissing: {
580+
type: 'boolean',
581+
},
574582
unnamedRootBase: {
575583
items: {
576584
type: 'string',

‎test/rules/assertions/requireParam.js‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2527,6 +2527,33 @@ export default {
25272527
}
25282528
`,
25292529
},
2530+
{
2531+
code: `
2532+
/**
2533+
* Some desc.
2534+
* @param a
2535+
*/
2536+
function quux (a, b) {}
2537+
`,
2538+
errors: [
2539+
{
2540+
message: 'Missing JSDoc @param "b" declaration.',
2541+
},
2542+
],
2543+
options: [
2544+
{
2545+
ignoreWhenAllParamsMissing: true,
2546+
}
2547+
],
2548+
output: `
2549+
/**
2550+
* Some desc.
2551+
* @param a
2552+
* @param b
2553+
*/
2554+
function quux (a, b) {}
2555+
`,
2556+
},
25302557
],
25312558
valid: [
25322559
{
@@ -3604,5 +3631,18 @@ export default {
36043631
}
36053632
},
36063633
},
3634+
{
3635+
code: `
3636+
/**
3637+
* Some desc.
3638+
*/
3639+
function quux (a, b) {}
3640+
`,
3641+
options: [
3642+
{
3643+
ignoreWhenAllParamsMissing: true,
3644+
}
3645+
],
3646+
},
36073647
],
36083648
};

0 commit comments

Comments
 (0)