Skip to content

Commit ba642e4

Browse files
seanpoulterseanpoulter
authored
feat(check-param-names): Add disableMissingParamChecks option (#1206)
1 parent ab893ba commit ba642e4

File tree

4 files changed

+157
-4
lines changed

4 files changed

+157
-4
lines changed

‎.README/rules/check-param-names.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,12 +81,16 @@ item at the same level is destructured as destructuring will prevent other
8181
access and this option is only intended to permit documenting extra properties
8282
that are available and actually used in the function.
8383

84+
### `disableMissingParamChecks`
85+
86+
Whether to avoid checks for missing `@param` definitions. Defaults to `false`. Change to `true` if you want to be able to omit properties.
87+
8488
## Context and settings
8589

8690
|||
8791
|---|---|
8892
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
89-
|Options|`allowExtraTrailingParamDocs`, `checkDestructured`, `checkRestProperty`, `checkTypesPattern`, `disableExtraPropertyReporting`, `enableFixer`, `useDefaultObjectProperties`|
93+
|Options|`allowExtraTrailingParamDocs`, `checkDestructured`, `checkRestProperty`, `checkTypesPattern`, `disableExtraPropertyReporting`, `disableMissingParamChecks`, `enableFixer`, `useDefaultObjectProperties`|
9094
|Tags|`param`|
9195
|Aliases|`arg`, `argument`|
9296
|Recommended|true|

‎docs/rules/check-param-names.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -116,14 +116,20 @@ item at the same level is destructured as destructuring will prevent other
116116
access and this option is only intended to permit documenting extra properties
117117
that are available and actually used in the function.
118118

119+
<a name="user-content-check-param-names-options-disableMissingParamChecks"></a>
120+
<a name="check-param-names-options-disableMissingParamChecks"></a>
121+
### <code>disableMissingParamChecks</code>
122+
123+
Whether to check for missing `@param` definitions. Defaults to `false`. Change to `true` if you want to be able to omit properties.
124+
119125
<a name="user-content-check-param-names-context-and-settings"></a>
120126
<a name="check-param-names-context-and-settings"></a>
121127
## Context and settings
122128

123129
|||
124130
|---|---|
125131
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
126-
|Options|`allowExtraTrailingParamDocs`, `checkDestructured`, `checkRestProperty`, `checkTypesPattern`, `disableExtraPropertyReporting`, `enableFixer`, `useDefaultObjectProperties`|
132+
|Options|`allowExtraTrailingParamDocs`, `checkDestructured`, `checkRestProperty`, `checkTypesPattern`, `disableExtraPropertyReporting`, `disableMissingParamChecks`, `enableFixer`, `useDefaultObjectProperties`|
127133
|Tags|`param`|
128134
|Aliases|`arg`, `argument`|
129135
|Recommended|true|

‎src/rules/checkParamNames.js

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import iterateJsdoc from '../iterateJsdoc.js';
77
* @param {boolean} checkRestProperty
88
* @param {RegExp} checkTypesRegex
99
* @param {boolean} disableExtraPropertyReporting
10+
* @param {boolean} disableMissingParamChecks
1011
* @param {boolean} enableFixer
1112
* @param {import('../jsdocUtils.js').ParamNameInfo[]} functionParameterNames
1213
* @param {import('comment-parser').Block} jsdoc
@@ -21,6 +22,7 @@ const validateParameterNames = (
2122
checkRestProperty,
2223
checkTypesRegex,
2324
disableExtraPropertyReporting,
25+
disableMissingParamChecks,
2426
enableFixer,
2527
functionParameterNames, jsdoc, utils, report,
2628
) => {
@@ -245,10 +247,20 @@ const validateParameterNames = (
245247
return item;
246248
}).filter((item) => {
247249
return item !== 'this';
248-
}).join(', ');
250+
});
251+
252+
// When disableMissingParamChecks is true tag names can be omitted.
253+
// Report when the tag names do not match the expected names or they are used out of order.
254+
if (disableMissingParamChecks) {
255+
const usedExpectedNames = expectedNames.map(a => a?.toString()).filter(expectedName => expectedName && actualNames.includes(expectedName));
256+
const usedInOrder = actualNames.every((actualName, idx) => actualName === usedExpectedNames[idx]);
257+
if (usedInOrder) {
258+
return false;
259+
}
260+
}
249261

250262
report(
251-
`Expected @${targetTagName} names to be "${expectedNames}". Got "${actualNames.join(', ')}".`,
263+
`Expected @${targetTagName} names to be "${expectedNames.join(', ')}". Got "${actualNames.join(', ')}".`,
252264
null,
253265
tag,
254266
);
@@ -329,6 +341,7 @@ export default iterateJsdoc(({
329341
enableFixer = false,
330342
useDefaultObjectProperties = false,
331343
disableExtraPropertyReporting = false,
344+
disableMissingParamChecks = false,
332345
} = context.options[0] || {};
333346

334347
const checkTypesRegex = utils.getRegexFromString(checkTypesPattern);
@@ -349,6 +362,7 @@ export default iterateJsdoc(({
349362
checkRestProperty,
350363
checkTypesRegex,
351364
disableExtraPropertyReporting,
365+
disableMissingParamChecks,
352366
enableFixer,
353367
functionParameterNames,
354368
jsdoc,
@@ -389,6 +403,9 @@ export default iterateJsdoc(({
389403
disableExtraPropertyReporting: {
390404
type: 'boolean',
391405
},
406+
disableMissingParamChecks: {
407+
type: 'boolean',
408+
},
392409
enableFixer: {
393410
type: 'boolean',
394411
},

‎test/rules/assertions/checkParamNames.js

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1183,6 +1183,89 @@ export default {
11831183
parser: typescriptEslintParser
11841184
},
11851185
},
1186+
{
1187+
code: `
1188+
/**
1189+
* @param foo
1190+
* @param foo.bar
1191+
*/
1192+
function quux (bar, foo) {
1193+
}
1194+
`,
1195+
options: [
1196+
{
1197+
disableMissingParamChecks: false,
1198+
},
1199+
],
1200+
errors: [
1201+
{
1202+
line: 3,
1203+
message: 'Expected @param names to be "bar, foo". Got "foo".',
1204+
},
1205+
],
1206+
},
1207+
{
1208+
code: `
1209+
/**
1210+
* @param foo
1211+
*/
1212+
function quux (bar, baz) {
1213+
}
1214+
`,
1215+
options: [
1216+
{
1217+
disableMissingParamChecks: true,
1218+
},
1219+
],
1220+
errors: [
1221+
{
1222+
line: 3,
1223+
message: 'Expected @param names to be "bar, baz". Got "foo".',
1224+
},
1225+
],
1226+
},
1227+
{
1228+
code: `
1229+
/**
1230+
* @param bar
1231+
* @param foo
1232+
*/
1233+
function quux (foo, bar) {
1234+
}
1235+
`,
1236+
options: [
1237+
{
1238+
disableMissingParamChecks: true,
1239+
},
1240+
],
1241+
errors: [
1242+
{
1243+
line: 3,
1244+
message: 'Expected @param names to be "foo, bar". Got "bar, foo".',
1245+
},
1246+
],
1247+
},
1248+
{
1249+
code: `
1250+
/**
1251+
* @param foo
1252+
* @param bar
1253+
*/
1254+
function quux (foo) {
1255+
}
1256+
`,
1257+
options: [
1258+
{
1259+
disableMissingParamChecks: true,
1260+
},
1261+
],
1262+
errors: [
1263+
{
1264+
line: 4,
1265+
message: '@param "bar" does not match an existing function parameter.',
1266+
},
1267+
],
1268+
},
11861269
],
11871270
valid: [
11881271
{
@@ -1835,5 +1918,48 @@ export default {
18351918
parser: typescriptEslintParser
18361919
},
18371920
},
1921+
{
1922+
code: `
1923+
/**
1924+
* Documentation
1925+
*/
1926+
function quux (foo, bar) {
1927+
}
1928+
`,
1929+
options: [
1930+
{
1931+
disableMissingParamChecks: true,
1932+
},
1933+
],
1934+
},
1935+
{
1936+
code: `
1937+
/**
1938+
* @param bar
1939+
* @param bar.baz
1940+
*/
1941+
function quux (foo, bar) {
1942+
}
1943+
`,
1944+
options: [
1945+
{
1946+
disableMissingParamChecks: true,
1947+
},
1948+
],
1949+
},
1950+
{
1951+
code: `
1952+
/**
1953+
* @param foo
1954+
*/
1955+
function quux (foo, bar) {
1956+
}
1957+
`,
1958+
options: [
1959+
{
1960+
disableMissingParamChecks: true,
1961+
},
1962+
],
1963+
},
18381964
],
18391965
};

0 commit comments

Comments
 (0)