Skip to content

feat(check-param-names): Add disableMissingParamChecks option #1206

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Feb 22, 2024
Merged

feat(check-param-names): Add disableMissingParamChecks option #1206

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
a2235fe
feat(check-param-names): Add disableMissingParamChecks option
seanpoulter Feb 21, 2024
bc4c4f7
test(require-param): Add missing line numbers in errors
seanpoulter Feb 21, 2024
091fe5f
Revert "test(require-param): Add missing line numbers in errors"
seanpoulter Feb 21, 2024
03db300
Add invalid test case for disableMissingParamChecks = true
seanpoulter Feb 21, 2024
55e5fc2
Add test case for extra, unexpected tag
seanpoulter Feb 21, 2024
b752b59
Add test case
seanpoulter Feb 21, 2024
d3a248d
Update src/rules/checkParamNames.js
seanpoulter Feb 22, 2024
133befa
Update .README/rules/check-param-names.md
seanpoulter Feb 22, 2024
5d57b1e
Update src/rules/checkParamNames.js
brettz9 Feb 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion .README/rules/check-param-names.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,12 +81,16 @@ item at the same level is destructured as destructuring will prevent other
access and this option is only intended to permit documenting extra properties
that are available and actually used in the function.

### `disableMissingParamChecks`

Whether to check for missing `@param` definitions. Defaults to `false`. Change to `true` if you want to be able to omit properties.

## Context and settings

|||
|---|---|
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
|Options|`allowExtraTrailingParamDocs`, `checkDestructured`, `checkRestProperty`, `checkTypesPattern`, `disableExtraPropertyReporting`, `enableFixer`, `useDefaultObjectProperties`|
|Options|`allowExtraTrailingParamDocs`, `checkDestructured`, `checkRestProperty`, `checkTypesPattern`, `disableExtraPropertyReporting`, `disableMissingParamChecks`, `enableFixer`, `useDefaultObjectProperties`|
|Tags|`param`|
|Aliases|`arg`, `argument`|
|Recommended|true|
Expand Down
8 changes: 7 additions & 1 deletion docs/rules/check-param-names.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,14 +116,20 @@ item at the same level is destructured as destructuring will prevent other
access and this option is only intended to permit documenting extra properties
that are available and actually used in the function.

<a name="user-content-check-param-names-options-disableMissingParamChecks"></a>
<a name="check-param-names-options-disableMissingParamChecks"></a>
### <code>disableMissingParamChecks</code>

Whether to check for missing `@param` definitions. Defaults to `false`. Change to `true` if you want to be able to omit properties.

<a name="user-content-check-param-names-context-and-settings"></a>
<a name="check-param-names-context-and-settings"></a>
## Context and settings

|||
|---|---|
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
|Options|`allowExtraTrailingParamDocs`, `checkDestructured`, `checkRestProperty`, `checkTypesPattern`, `disableExtraPropertyReporting`, `enableFixer`, `useDefaultObjectProperties`|
|Options|`allowExtraTrailingParamDocs`, `checkDestructured`, `checkRestProperty`, `checkTypesPattern`, `disableExtraPropertyReporting`, `disableMissingParamChecks`, `enableFixer`, `useDefaultObjectProperties`|
|Tags|`param`|
|Aliases|`arg`, `argument`|
|Recommended|true|
Expand Down
9 changes: 8 additions & 1 deletion src/rules/checkParamNames.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import iterateJsdoc from '../iterateJsdoc.js';
* @param {boolean} checkRestProperty
* @param {RegExp} checkTypesRegex
* @param {boolean} disableExtraPropertyReporting
* @param {boolean} disableMissingParamChecks
* @param {boolean} enableFixer
* @param {import('../jsdocUtils.js').ParamNameInfo[]} functionParameterNames
* @param {import('comment-parser').Block} jsdoc
Expand All @@ -21,6 +22,7 @@ const validateParameterNames = (
checkRestProperty,
checkTypesRegex,
disableExtraPropertyReporting,
disableMissingParamChecks,
enableFixer,
functionParameterNames, jsdoc, utils, report,
) => {
Expand Down Expand Up @@ -225,7 +227,7 @@ const validateParameterNames = (
funcParamName = functionParameterName;
}

if (funcParamName !== tag.name.trim()) {
if (funcParamName !== tag.name.trim() && !disableMissingParamChecks) {
// Todo: Improve for array or object child items
const actualNames = paramTagsNonNested.map(([
, {
Expand Down Expand Up @@ -329,6 +331,7 @@ export default iterateJsdoc(({
enableFixer = false,
useDefaultObjectProperties = false,
disableExtraPropertyReporting = false,
disableMissingParamChecks = false,
} = context.options[0] || {};

const checkTypesRegex = utils.getRegexFromString(checkTypesPattern);
Expand All @@ -349,6 +352,7 @@ export default iterateJsdoc(({
checkRestProperty,
checkTypesRegex,
disableExtraPropertyReporting,
disableMissingParamChecks,
enableFixer,
functionParameterNames,
jsdoc,
Expand Down Expand Up @@ -389,6 +393,9 @@ export default iterateJsdoc(({
disableExtraPropertyReporting: {
type: 'boolean',
},
disableMissingParamChecks: {
type: 'boolean',
},
enableFixer: {
type: 'boolean',
},
Expand Down
36 changes: 36 additions & 0 deletions test/rules/assertions/checkParamNames.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1183,6 +1183,27 @@ export default {
parser: typescriptEslintParser
},
},
{
code: `
/**
* @param foo
* @param foo.bar
*/
function quux (bar, foo) {
}
`,
options: [
{
disableMissingParamChecks: false,
},
],
errors: [
{
line: 3,
message: 'Expected @param names to be "bar, foo". Got "foo".',
},
],
}
],
valid: [
{
Expand Down Expand Up @@ -1835,5 +1856,20 @@ export default {
parser: typescriptEslintParser
},
},
{
code: `
/**
* @param foo
* @param foo.bar
*/
function quux (bar, foo) {
}
`,
options: [
{
disableMissingParamChecks: true,
},
],
}
],
};
30 changes: 30 additions & 0 deletions test/rules/assertions/requireParam.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -292,6 +292,7 @@ export default {
`,
errors: [
{
line: 2,
message: 'Missing JSDoc @param "options.foo" declaration.',
},
],
Expand Down Expand Up @@ -1783,6 +1784,7 @@ export default {
`,
errors: [
{
line: 2,
message: 'Missing JSDoc @param "options.foo" declaration.',
},
],
Expand Down Expand Up @@ -1828,6 +1830,7 @@ export default {
`,
errors: [
{
line: 3,
message: 'Missing JSDoc @param "options.permissions" declaration.',
},
],
Expand Down Expand Up @@ -1943,6 +1946,7 @@ export default {
`,
errors: [
{
line: 2,
message: 'Missing JSDoc @param "cfg.extra" declaration.',
},
],
Expand Down Expand Up @@ -1976,6 +1980,7 @@ export default {
`,
errors: [
{
line: 2,
message: 'Missing JSDoc @param "cfg.opts.extra" declaration.',
},
],
Expand Down Expand Up @@ -2010,6 +2015,7 @@ export default {
`,
errors: [
{
line: 2,
message: 'Missing JSDoc @param "cfg."1"" declaration.',
},
],
Expand Down Expand Up @@ -2067,15 +2073,19 @@ export default {
`,
errors: [
{
line: 2,
message: 'Missing JSDoc @param "bbox.x" declaration.',
},
{
line: 2,
message: 'Missing JSDoc @param "bbox.y" declaration.',
},
{
line: 2,
message: 'Missing JSDoc @param "bbox.width" declaration.',
},
{
line: 2,
message: 'Missing JSDoc @param "bbox.height" declaration.',
},
],
Expand Down Expand Up @@ -2110,15 +2120,19 @@ export default {
`,
errors: [
{
line: 2,
message: 'Missing JSDoc @param "bbox.x" declaration.',
},
{
line: 2,
message: 'Missing JSDoc @param "bbox.y" declaration.',
},
{
line: 2,
message: 'Missing JSDoc @param "bbox.width" declaration.',
},
{
line: 2,
message: 'Missing JSDoc @param "bbox.height" declaration.',
},
],
Expand Down Expand Up @@ -2149,9 +2163,11 @@ export default {
`,
errors: [
{
line: 3,
message: 'Missing JSDoc @param "fetchOptions.url" declaration.',
},
{
line: 3,
message: 'Missing JSDoc @param "fetchOptions.options" declaration.',
},
],
Expand Down Expand Up @@ -2218,6 +2234,7 @@ export default {
`,
errors: [
{
line: 2,
message: 'Missing JSDoc @param "options.foo.bar" declaration.',
},
],
Expand All @@ -2242,6 +2259,7 @@ export default {
`,
errors: [
{
line: 2,
message: 'Missing JSDoc @param "options.foo.bar" declaration.',
},
],
Expand Down Expand Up @@ -2271,9 +2289,11 @@ export default {
`,
errors: [
{
line: 2,
message: 'Missing JSDoc @param "options.foo" declaration.',
},
{
line: 2,
message: 'Missing JSDoc @param "options.foo.bar" declaration.',
},
],
Expand All @@ -2299,6 +2319,7 @@ export default {
`,
errors: [
{
line: 2,
message: 'Missing JSDoc @param "options.foo.bar" declaration.',
},
],
Expand All @@ -2324,6 +2345,7 @@ export default {
`,
errors: [
{
line: 2,
message: 'Missing JSDoc @param "options.foo.bar.baz" declaration.',
},
],
Expand Down Expand Up @@ -2351,9 +2373,11 @@ export default {
`,
errors: [
{
line: 2,
message: 'Missing JSDoc @param "props.prop.a" declaration.',
},
{
line: 2,
message: 'Missing JSDoc @param "props.prop.b" declaration.',
},
],
Expand Down Expand Up @@ -2385,12 +2409,15 @@ export default {
`,
errors: [
{
line: 2,
message: 'Missing JSDoc @param "a" declaration.',
},
{
line: 2,
message: 'Missing JSDoc @param "b" declaration.',
},
{
line: 2,
message: 'Missing JSDoc @param "c" declaration.',
},
],
Expand All @@ -2414,6 +2441,7 @@ export default {
`,
errors: [
{
line: 2,
message: 'Missing JSDoc @param "baz" declaration.',
},
],
Expand Down Expand Up @@ -2455,6 +2483,7 @@ export default {
`,
errors: [
{
line: 2,
message: 'Missing JSDoc @param "verbose" declaration.',
},
],
Expand Down Expand Up @@ -2502,6 +2531,7 @@ export default {
`,
errors: [
{
line: 6,
message: 'Missing JSDoc @param "btnState" declaration.',
},
],
Expand Down