diff --git a/.README/rules/check-param-names.md b/.README/rules/check-param-names.md index f05b12d64..64ed44046 100644 --- a/.README/rules/check-param-names.md +++ b/.README/rules/check-param-names.md @@ -2,9 +2,19 @@ Ensures that parameter names in JSDoc match those in the function declaration. +#### Options + +##### `allowExtraTrailingParamDocs` + +If set to `true`, this option will allow extra `@param` definitions (e.g., +representing future expected or virtual params) to be present without needing +their presence within the function signature. Other inconsistencies between +`@param`'s and present function parameters will still be reported. + ||| |---|---| |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`| +|Options|`allowExtraTrailingParamDocs`| |Tags|`param`| diff --git a/README.md b/README.md index a6924f3ec..5bdafa951 100644 --- a/README.md +++ b/README.md @@ -1403,9 +1403,21 @@ function quux () { Ensures that parameter names in JSDoc match those in the function declaration. + +#### Options + + +##### allowExtraTrailingParamDocs + +If set to `true`, this option will allow extra `@param` definitions (e.g., +representing future expected or virtual params) to be present without needing +their presence within the function signature. Other inconsistencies between +`@param`'s and present function parameters will still be reported. + ||| |---|---| |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`| +|Options|`allowExtraTrailingParamDocs`| |Tags|`param`| The following patterns are considered problems: @@ -1618,6 +1630,15 @@ export class SomeClass { */ function quux (error, code = 1) { }; + +/** + * @param foo + * @param bar + */ +function quux (foo) { + +} +// Options: [{"allowExtraTrailingParamDocs":true}] ```` @@ -1840,10 +1861,10 @@ wizaction Note that the tags indicated as replacements in `settings.jsdoc.tagNamePreference` will automatically be considered as valid. - + #### Options - + ##### definedTags Use an array of `definedTags` strings to configure additional, allowed tags. @@ -2443,7 +2464,7 @@ Date RegExp ``` - + #### Options `check-types` allows one option: @@ -3281,22 +3302,22 @@ This rule checks the values for a handful of tags: `allowedAuthors` is present, ensure that the author value is one of these array items. - + #### Options - + ##### allowedAuthors An array of allowable author values. If absent, only non-whitespace will be checked for. - + ##### allowedLicenses An array of allowable license values or `true` to allow any license text. If present as an array, will be used in place of SPDX identifiers. - + ##### licensePattern A string to be converted into a `RegExp` (with `u` flag) and whose first @@ -3525,10 +3546,10 @@ is set to "closure" (which allows types). - `@public` - `@static` - + #### Options - + ##### tags If you want additional tags to be checked for their descriptions, you may @@ -3743,10 +3764,10 @@ by our supported Node versions): Applies to the jsdoc block description and `@description` (or `@desc`) by default but the `tags` option (see below) may be used to match other tags. - + #### Options - + ##### matchDescription You can supply your own expression to override the default, passing a @@ -3761,7 +3782,7 @@ You can supply your own expression to override the default, passing a As with the default, the supplied regular expression will be applied with the Unicode (`"u"`) flag and is *not* case-insensitive. - + ##### tags If you want different regular expressions to apply to tags, you may use @@ -3798,7 +3819,7 @@ its "description" (e.g., for `@returns {someType} some description`, the description is `some description` while for `@some-tag xyz`, the description is `xyz`). - + ##### mainDescription If you wish to override the main function description without changing the @@ -3820,7 +3841,7 @@ There is no need to add `mainDescription: true`, as by default, the main function (and only the main function) is linted, though you may disable checking it by setting it to `false`. - + ##### contexts Set this to an array of strings representing the AST context @@ -4440,7 +4461,7 @@ function quux () { Enforces a consistent padding of the block description. - + #### Options This rule allows one optional string argument. If it is `"always"` then a problem is raised when there is no newline after the description. If it is `"never"` then a problem is raised when there is a newline after the description. The default value is `"always"`. @@ -4711,7 +4732,7 @@ The following types are always considered defined. Note that preferred types indicated within `settings.jsdoc.preferredTypes` will also be assumed to be defined. - + #### Options An option object may have the following key: @@ -5121,10 +5142,10 @@ tag descriptions are written in complete sentences, i.e., * A colon or semi-colon followed by two line breaks is still part of the containing paragraph (unlike normal dual line breaks). - + #### Options - + ##### tags If you want additional tags to be checked for their descriptions, you may @@ -5612,7 +5633,7 @@ Requires that all functions have a description. `"tag"`) must have a non-empty description that explains the purpose of the method. - + #### Options An options object may have any of the following properties: @@ -5897,25 +5918,25 @@ Requires that all functions have examples. * All functions must have one or more `@example` tags. * Every example tag must have a non-empty description that explains the method's usage. - + #### Options This rule has an object option. - + ##### exemptedBy Array of tags (e.g., `['type']`) whose presence on the document block avoids the need for an `@example`. Defaults to an empty array. - + ##### avoidExampleOnConstructors Set to `true` to avoid the need for an example on a constructor (whether indicated as such by a jsdoc tag or by being within an ES6 `class`). Defaults to `false`. - + ##### contexts Set this to an array of strings representing the AST context @@ -6093,7 +6114,7 @@ function quux () { Requires a hyphen before the `@param` description. - + #### Options This rule takes one optional string argument. If it is `"always"` then a problem is raised when there is no hyphen before the description. If it is `"never"` then a problem is raised when there is a hyphen before the description. The default value is `"always"`. @@ -6199,7 +6220,7 @@ function quux () { Checks for presence of jsdoc comments, on class declarations as well as functions. - + #### Options Accepts one optional options object with the following optional keys. @@ -7387,7 +7408,7 @@ function quux (foo) { Requires that all function parameters are documented. - + #### Options An options object accepts one optional property: @@ -8487,7 +8508,7 @@ Requires returns are documented. Will also report if multiple `@returns` tags are present. - + #### Options - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document @@ -8989,7 +9010,7 @@ Also impacts behaviors on namepath (or event)-defining and pointing tags: allow `#`, `.`, or `~` at the end (which is not allowed at the end of normal paths). - + #### Options - `allowEmptyNamepaths` (default: true) - Set to `false` to disallow diff --git a/src/rules/checkParamNames.js b/src/rules/checkParamNames.js index 315f13580..28c2b0329 100644 --- a/src/rules/checkParamNames.js +++ b/src/rules/checkParamNames.js @@ -1,7 +1,10 @@ import entries from 'object.entries-ponyfill'; import iterateJsdoc from '../iterateJsdoc'; -const validateParameterNames = (targetTagName : string, functionParameterNames : Array, jsdoc, jsdocNode, utils, report) => { +const validateParameterNames = ( + targetTagName : string, allowExtraTrailingParamDocs: boolean, + functionParameterNames : Array, jsdoc, jsdocNode, utils, report, +) => { if (!jsdoc || !jsdoc.tags) { return false; } @@ -27,6 +30,10 @@ const validateParameterNames = (targetTagName : string, functionParameterNames : const functionParameterName = functionParameterNames[index]; if (!functionParameterName) { + if (allowExtraTrailingParamDocs) { + return false; + } + report( `@${targetTagName} "${tag.name}" does not match an existing function parameter.`, null, @@ -59,7 +66,10 @@ const validateParameterNames = (targetTagName : string, functionParameterNames : }); }; -const validateParameterNamesDeep = (targetTagName : string, jsdocParameterNames : Array, jsdoc, report : Function) => { +const validateParameterNamesDeep = ( + targetTagName : string, allowExtraTrailingParamDocs: boolean, + jsdocParameterNames : Array, jsdoc, report : Function, +) => { let lastRealParameter; return jsdocParameterNames.some((jsdocParameterName, idx) => { @@ -97,27 +107,47 @@ const validateParameterNamesDeep = (targetTagName : string, jsdocParameterNames }; export default iterateJsdoc(({ + context, jsdoc, jsdocNode, report, utils, }) => { - const functionParameterNames = utils.getFunctionParameterNames(); + const {allowExtraTrailingParamDocs} = context.options[0] || {}; + const jsdocParameterNamesDeep = utils.getJsdocParameterNamesDeep(); if (!jsdocParameterNamesDeep) { return; } + const functionParameterNames = utils.getFunctionParameterNames(); const targetTagName = utils.getPreferredTagName({tagName: 'param'}); - const isError = validateParameterNames(targetTagName, functionParameterNames, jsdoc, jsdocNode, utils, report); + const isError = validateParameterNames( + targetTagName, allowExtraTrailingParamDocs, functionParameterNames, + jsdoc, jsdocNode, utils, report, + ); if (isError) { return; } - validateParameterNamesDeep(targetTagName, jsdocParameterNamesDeep, jsdoc, report); + validateParameterNamesDeep( + targetTagName, allowExtraTrailingParamDocs, jsdocParameterNamesDeep, + jsdoc, report, + ); }, { meta: { fixable: 'code', + schema: [ + { + additionalProperties: false, + properties: { + allowExtraTrailingParamDocs: { + type: 'boolean', + }, + }, + type: 'object', + }, + ], type: 'suggestion', }, }); diff --git a/test/rules/assertions/checkParamNames.js b/test/rules/assertions/checkParamNames.js index 93e467a13..e9d05aca9 100644 --- a/test/rules/assertions/checkParamNames.js +++ b/test/rules/assertions/checkParamNames.js @@ -380,5 +380,21 @@ export default { }; `, }, + { + code: ` + /** + * @param foo + * @param bar + */ + function quux (foo) { + + } + `, + options: [ + { + allowExtraTrailingParamDocs: true, + }, + ], + }, ], };