diff --git a/.README/rules/check-values.md b/.README/rules/check-values.md index ab63031c0..b8a1d992d 100644 --- a/.README/rules/check-values.md +++ b/.README/rules/check-values.md @@ -7,9 +7,11 @@ This rule checks the values for a handful of tags: 2. `@since` - As with `@version` 3. `@license` - Checks that there is a present and valid SPDX identifier or is present within an `allowedLicenses` option. -4. `@author` - Checks there is a value present, and if the option +4. `@author` - Checks that there is a value present, and if the option `allowedAuthors` is present, ensure that the author value is one of these array items. +5. `@variation` - Checks that there iis a value present, and that it is + an integer. #### Options @@ -39,7 +41,7 @@ your expression as a string, but like a literal, e.g., `/^mit$/ui`. ||| |---|---| |Context|everywhere| -|Tags|`@version`, `@since`, `@license`, `@author`| +|Tags|`@version`, `@since`, `@license`, `@author`, `@variation`| |Recommended|true| |Options|`allowedAuthors`, `allowedLicenses`, `licensePattern`| |Settings|`tagNamePreference`| diff --git a/README.md b/README.md index 1359531c1..f69f2d6bb 100644 --- a/README.md +++ b/README.md @@ -5567,9 +5567,11 @@ This rule checks the values for a handful of tags: 2. `@since` - As with `@version` 3. `@license` - Checks that there is a present and valid SPDX identifier or is present within an `allowedLicenses` option. -4. `@author` - Checks there is a value present, and if the option +4. `@author` - Checks that there is a value present, and if the option `allowedAuthors` is present, ensure that the author value is one of these array items. +5. `@variation` - Checks that there iis a value present, and that it is + an integer. #### Options @@ -5603,7 +5605,7 @@ your expression as a string, but like a literal, e.g., `/^mit$/ui`. ||| |---|---| |Context|everywhere| -|Tags|`@version`, `@since`, `@license`, `@author`| +|Tags|`@version`, `@since`, `@license`, `@author`, `@variation`| |Recommended|true| |Options|`allowedAuthors`, `allowedLicenses`, `licensePattern`| |Settings|`tagNamePreference`| @@ -5627,6 +5629,14 @@ function quux (foo) { } // Message: Invalid JSDoc @version: "3.1". +/** + * @variation -3 + */ +function quux (foo) { + +} +// Message: Invalid JSDoc @variation: "-3". + /** * @since */ @@ -5712,6 +5722,22 @@ function quux (foo) { } // "jsdoc/check-values": ["error"|"warn", {"allowedAuthors":["Gajus Kuizinas","golopot"]}] // Message: Invalid JSDoc @author: "Brett Zamir"; expected one of Gajus Kuizinas, golopot. + +/** + * @variation + */ +function quux (foo) { + +} +// Message: Missing JSDoc @variation. + +/** + * @variation 5.2 + */ +function quux (foo) { + +} +// Message: Invalid JSDoc @variation: "5.2". ```` The following patterns are not considered problems: @@ -5806,6 +5832,13 @@ function quux (foo) { } // "jsdoc/check-values": ["error"|"warn", {"allowedAuthors":["Gajus Kuizinas","golopot","Brett Zamir"]}] + +/** + * @variation 3 + */ +function quux (foo) { + +} ```` diff --git a/src/rules/checkValues.js b/src/rules/checkValues.js index c419077d3..9a11f675d 100644 --- a/src/rules/checkValues.js +++ b/src/rules/checkValues.js @@ -30,6 +30,25 @@ export default iterateJsdoc(({ ); } }); + utils.forEachPreferredTag('variation', (jsdocParameter, targetTagName) => { + const variation = utils.getTagDescription(jsdocParameter).trim(); + if (!variation) { + report( + `Missing JSDoc @${targetTagName}.`, + null, + jsdocParameter, + ); + } else if ( + !Number.isInteger(Number(variation)) || + Number(variation) <= 0 + ) { + report( + `Invalid JSDoc @${targetTagName}: "${utils.getTagDescription(jsdocParameter)}".`, + null, + jsdocParameter, + ); + } + }); utils.forEachPreferredTag('since', (jsdocParameter, targetTagName) => { const version = utils.getTagDescription(jsdocParameter).trim(); if (!version) { diff --git a/test/rules/assertions/checkValues.js b/test/rules/assertions/checkValues.js index a6945adf7..6cba2b6c6 100644 --- a/test/rules/assertions/checkValues.js +++ b/test/rules/assertions/checkValues.js @@ -32,6 +32,22 @@ export default { }, ], }, + { + code: ` + /** + * @variation -3 + */ + function quux (foo) { + + } + `, + errors: [ + { + line: 3, + message: 'Invalid JSDoc @variation: "-3".', + }, + ], + }, { code: ` /** @@ -209,6 +225,38 @@ export default { }, ], }, + { + code: ` + /** + * @variation + */ + function quux (foo) { + + } + `, + errors: [ + { + line: 3, + message: 'Missing JSDoc @variation.', + }, + ], + }, + { + code: ` + /** + * @variation 5.2 + */ + function quux (foo) { + + } + `, + errors: [ + { + line: 3, + message: 'Invalid JSDoc @variation: "5.2".', + }, + ], + }, ], valid: [ { @@ -353,5 +401,15 @@ export default { }, ], }, + { + code: ` + /** + * @variation 3 + */ + function quux (foo) { + + } + `, + }, ], };