From eb92080fe36f434e5cf1ccb5884e72d1bb8a8a1f Mon Sep 17 00:00:00 2001 From: Brett Zamir Date: Thu, 10 Feb 2022 01:28:17 +0800 Subject: [PATCH] feat(`check-values`): add checking of `kind` Also, updates jsdoccomment and devDeps. --- .README/rules/check-values.md | 5 +++- README.md | 28 +++++++++++++++++- package.json | 6 ++-- src/rules/checkValues.js | 35 ++++++++++++++++++++++ test/rules/assertions/checkValues.js | 44 ++++++++++++++++++++++++++++ 5 files changed, 113 insertions(+), 5 deletions(-) diff --git a/.README/rules/check-values.md b/.README/rules/check-values.md index 802d5ec8c..072abb86f 100644 --- a/.README/rules/check-values.md +++ b/.README/rules/check-values.md @@ -13,6 +13,9 @@ This rule checks the values for a handful of tags: 5. `@variation` - If `numericOnlyVariation` is set, will checks that there is a value present, and that it is an integer (otherwise, jsdoc allows any value). +6. `@kind` - Insists that it be one of the allowed values: 'class', + 'constant', 'event', 'external', 'file', 'function', 'member', 'mixin', + 'module', 'namespace', 'typedef', #### Options @@ -47,7 +50,7 @@ Whether to enable validation that `@variation` must be a number. Defaults to ||| |---|---| |Context|everywhere| -|Tags|`@version`, `@since`, `@license`, `@author`, `@variation`| +|Tags|`@version`, `@since`, `@kind`, `@license`, `@author`, `@variation`| |Recommended|true| |Options|`allowedAuthors`, `allowedLicenses`, `licensePattern`| |Settings|`tagNamePreference`| diff --git a/README.md b/README.md index 4981edb90..1e3406078 100644 --- a/README.md +++ b/README.md @@ -5818,6 +5818,9 @@ This rule checks the values for a handful of tags: 5. `@variation` - If `numericOnlyVariation` is set, will checks that there is a value present, and that it is an integer (otherwise, jsdoc allows any value). +6. `@kind` - Insists that it be one of the allowed values: 'class', + 'constant', 'event', 'external', 'file', 'function', 'member', 'mixin', + 'module', 'namespace', 'typedef', #### Options @@ -5857,7 +5860,7 @@ Whether to enable validation that `@variation` must be a number. Defaults to ||| |---|---| |Context|everywhere| -|Tags|`@version`, `@since`, `@license`, `@author`, `@variation`| +|Tags|`@version`, `@since`, `@kind`, `@license`, `@author`, `@variation`| |Recommended|true| |Options|`allowedAuthors`, `allowedLicenses`, `licensePattern`| |Settings|`tagNamePreference`| @@ -5881,6 +5884,22 @@ function quux (foo) { } // Message: Invalid JSDoc @version: "3.1". +/** + * @kind + */ +function quux (foo) { + +} +// Message: Missing JSDoc @kind value. + +/** + * @kind -3 + */ +function quux (foo) { + +} +// Message: Invalid JSDoc @kind: "-3"; must be one of: class, constant, event, external, file, function, member, mixin, module, namespace, typedef. + /** * @variation -3 */ @@ -6108,6 +6127,13 @@ function quux (foo) { * @license MIT */ 'use strict'; + +/** + * @kind function + */ +function quux (foo) { + +} ```` diff --git a/package.json b/package.json index 9773f7684..8575c401d 100644 --- a/package.json +++ b/package.json @@ -5,7 +5,7 @@ "url": "http://gajus.com" }, "dependencies": { - "@es-joy/jsdoccomment": "~0.18.0", + "@es-joy/jsdoccomment": "~0.19.0", "comment-parser": "1.3.0", "debug": "^4.3.3", "escape-string-regexp": "^4.0.0", @@ -17,7 +17,7 @@ "description": "JSDoc linting rules for ESLint.", "devDependencies": { "@babel/cli": "^7.17.0", - "@babel/core": "^7.17.0", + "@babel/core": "^7.17.2", "@babel/eslint-parser": "^7.17.0", "@babel/node": "^7.16.8", "@babel/plugin-syntax-class-properties": "^7.12.13", @@ -25,7 +25,7 @@ "@babel/preset-env": "^7.16.11", "@babel/register": "^7.17.0", "@hkdobrev/run-if-changed": "^0.3.1", - "@typescript-eslint/parser": "^5.10.2", + "@typescript-eslint/parser": "^5.11.0", "babel-plugin-add-module-exports": "^1.0.4", "babel-plugin-istanbul": "^6.1.1", "camelcase": "^6.3.0", diff --git a/src/rules/checkValues.js b/src/rules/checkValues.js index 924b146b1..254faf015 100644 --- a/src/rules/checkValues.js +++ b/src/rules/checkValues.js @@ -2,6 +2,20 @@ import semver from 'semver'; import spdxExpressionParse from 'spdx-expression-parse'; import iterateJsdoc from '../iterateJsdoc'; +const allowedKinds = new Set([ + 'class', + 'constant', + 'event', + 'external', + 'file', + 'function', + 'member', + 'mixin', + 'module', + 'namespace', + 'typedef', +]); + export default iterateJsdoc(({ utils, report, @@ -31,6 +45,27 @@ export default iterateJsdoc(({ ); } }); + + utils.forEachPreferredTag('kind', (jsdocParameter, targetTagName) => { + const kind = utils.getTagDescription(jsdocParameter).trim(); + if (!kind) { + report( + `Missing JSDoc @${targetTagName} value.`, + null, + jsdocParameter, + ); + } else if (!allowedKinds.has(kind)) { + report( + `Invalid JSDoc @${targetTagName}: "${utils.getTagDescription(jsdocParameter)}"; ` + + `must be one of: ${[ + ...allowedKinds, + ].join(', ')}.`, + null, + jsdocParameter, + ); + } + }); + if (numericOnlyVariation) { utils.forEachPreferredTag('variation', (jsdocParameter, targetTagName) => { const variation = utils.getTagDescription(jsdocParameter).trim(); diff --git a/test/rules/assertions/checkValues.js b/test/rules/assertions/checkValues.js index 0cfa945fb..289d6c760 100644 --- a/test/rules/assertions/checkValues.js +++ b/test/rules/assertions/checkValues.js @@ -32,6 +32,40 @@ export default { }, ], }, + { + code: ` + /** + * @kind + */ + function quux (foo) { + + } + `, + errors: [ + { + line: 3, + message: 'Missing JSDoc @kind value.', + }, + ], + }, + { + code: ` + /** + * @kind -3 + */ + function quux (foo) { + + } + `, + errors: [ + { + line: 3, + message: 'Invalid JSDoc @kind: "-3"; must be one of: class, ' + + 'constant, event, external, file, function, member, mixin, ' + + 'module, namespace, typedef.', + }, + ], + }, { code: ` /** @@ -458,5 +492,15 @@ export default { 'use strict'; `, }, + { + code: ` + /** + * @kind function + */ + function quux (foo) { + + } + `, + }, ], };