Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(
no-defaults
): add new rule to reports defaults on @param
or …
…`@default` and optionally report optional args; fixes #477
- Loading branch information
Showing
6 changed files
with
410 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,42 @@ | ||
### `no-defaults` | ||
|
||
This rule reports defaults being used on the relevant portion of `@param` | ||
or `@default`. It also optionally reports the presence of the | ||
square-bracketed optional arguments at all. | ||
|
||
The rule is intended to prevent the indication of defaults on tags where | ||
this would be redundant with ES6 default parameters (or for `@default`, | ||
where it would be redundant with the context to which the `@default` | ||
tag is attached). | ||
|
||
Unless your `@default` is on a function, you will need to set `contexts` | ||
to an appropriate context, including, if you wish, "any". | ||
|
||
#### Options | ||
|
||
##### `noOptionalParamNames` | ||
|
||
Set this to `true` to report the presence of optional parameters. May be | ||
used if the project is insisting on optionality being indicated by | ||
the presence of ES6 default parameters (bearing in mind that such | ||
"defaults" are only applied when the supplied value is missing or | ||
`undefined` but not for `null` or other "falsey" values). | ||
|
||
##### `contexts` | ||
|
||
Set this to an array of strings representing the AST context | ||
where you wish the rule to be applied. | ||
Overrides the default contexts (see below). Set to `"any"` if you want | ||
the rule to apply to any jsdoc block throughout your files (as is necessary | ||
for finding function blocks not attached to a function declaration or | ||
expression, i.e., `@callback` or `@function` (or its aliases `@func` or | ||
`@method`) (including those associated with an `@interface`). | ||
|
||
||| | ||
|---|---| | ||
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled| | ||
|Tags|`param`, `default`| | ||
|Aliases|`arg`, `argument`, `defaultvalue`| | ||
|Options|`contexts`, `noOptionalParamNames`| | ||
|
||
<!-- assertions noDefaults --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,52 @@ | ||
import iterateJsdoc from '../iterateJsdoc'; | ||
|
||
export default iterateJsdoc(({ | ||
context, | ||
utils, | ||
}) => { | ||
const {noOptionalParamNames} = context.options[0] || {}; | ||
const paramTags = utils.getPresentTags(['param', 'arg', 'argument']); | ||
paramTags.forEach((tag) => { | ||
if (noOptionalParamNames && tag.optional) { | ||
utils.reportJSDoc(`Optional param names are not permitted on @${tag.tag}.`, tag, () => { | ||
tag.default = ''; | ||
tag.optional = false; | ||
}); | ||
} else if (tag.default) { | ||
utils.reportJSDoc(`Defaults are not permitted on @${tag.tag}.`, tag, () => { | ||
tag.default = ''; | ||
}); | ||
} | ||
}); | ||
const defaultTags = utils.getPresentTags(['default', 'defaultvalue']); | ||
defaultTags.forEach((tag) => { | ||
if (tag.description) { | ||
utils.reportJSDoc(`Default values are not permitted on @${tag.tag}.`, tag, () => { | ||
tag.description = ''; | ||
}); | ||
} | ||
}); | ||
}, { | ||
contextDefaults: true, | ||
meta: { | ||
fixable: 'code', | ||
schema: [ | ||
{ | ||
additionalProperties: false, | ||
properties: { | ||
contexts: { | ||
items: { | ||
type: 'string', | ||
}, | ||
type: 'array', | ||
}, | ||
noOptionalParamNames: { | ||
type: 'boolean', | ||
}, | ||
}, | ||
type: 'object', | ||
}, | ||
], | ||
type: 'suggestion', | ||
}, | ||
}); |
Oops, something went wrong.