diff --git a/.README/README.md b/.README/README.md index 595e2d0ac..501a3c6e7 100644 --- a/.README/README.md +++ b/.README/README.md @@ -557,6 +557,7 @@ selector). {"gitdown": "include", "file": "./rules/no-bad-blocks.md"} {"gitdown": "include", "file": "./rules/no-defaults.md"} {"gitdown": "include", "file": "./rules/no-missing-syntax.md"} +{"gitdown": "include", "file": "./rules/no-multi-asterisks.md"} {"gitdown": "include", "file": "./rules/no-restricted-syntax.md"} {"gitdown": "include", "file": "./rules/no-types.md"} {"gitdown": "include", "file": "./rules/no-undefined-types.md"} diff --git a/.README/rules/no-multi-asterisks.md b/.README/rules/no-multi-asterisks.md new file mode 100644 index 000000000..3d30ea8b3 --- /dev/null +++ b/.README/rules/no-multi-asterisks.md @@ -0,0 +1,41 @@ +### `no-multi-asterisks` + +Prevents use of multiple asterisks at the beginning of lines. + +Note that if you wish to prevent multiple asterisks at the very beginning of +the jsdoc block, you should use `no-bad-blocks` (as that is not proper jsdoc +and that rule is for catching blocks which only seem like jsdoc). + +#### Options + +##### `preventAtMiddleLines` (defaults to `true`) + +Prevent the likes of this: + +```js +/** + * + ** + */ +``` + +##### `preventAtEnd` (defaults to `true`) + +Prevent the likes of this: + +```js +/** + * + * + **/ +``` + +||| +|---|---| +|Context|everywhere| +|Tags|(any)| +|Recommended|true| +|Settings|| +|Options|`preventAtEnd`, `preventAtMiddleLines`| + + diff --git a/README.md b/README.md index 3b56f58b5..11d4dd1ac 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,7 @@ JSDoc linting rules for ESLint. * [`no-bad-blocks`](#eslint-plugin-jsdoc-rules-no-bad-blocks) * [`no-defaults`](#eslint-plugin-jsdoc-rules-no-defaults) * [`no-missing-syntax`](#eslint-plugin-jsdoc-rules-no-missing-syntax) + * [`no-multi-asterisks`](#eslint-plugin-jsdoc-rules-no-multi-asterisks) * [`no-restricted-syntax`](#eslint-plugin-jsdoc-rules-no-restricted-syntax) * [`no-types`](#eslint-plugin-jsdoc-rules-no-types) * [`no-undefined-types`](#eslint-plugin-jsdoc-rules-no-undefined-types) @@ -8086,6 +8087,167 @@ function baz () { ```` + +### no-multi-asterisks + +Prevents use of multiple asterisks at the beginning of lines. + +Note that if you wish to prevent multiple asterisks at the very beginning of +the jsdoc block, you should use `no-bad-blocks` (as that is not proper jsdoc +and that rule is for catching blocks which only seem like jsdoc). + + +#### Options + + +##### preventAtMiddleLines (defaults to true) + +Prevent the likes of this: + +```js +/** + * + ** + */ +``` + + +##### preventAtEnd (defaults to true) + +Prevent the likes of this: + +```js +/** + * + * + **/ +``` + +||| +|---|---| +|Context|everywhere| +|Tags|(any)| +|Recommended|true| +|Settings|| +|Options|`preventAtEnd`, `preventAtMiddleLines`| + +The following patterns are considered problems: + +````js +/** + * + ** + */ +// Message: Should be no multiple asterisks on middle lines. + +/** + * + ** + */ +// "jsdoc/no-multi-asterisks": ["error"|"warn", {"preventAtMiddleLines":true}] +// Message: Should be no multiple asterisks on middle lines. + +/** + * + ** + */ +// "jsdoc/no-multi-asterisks": ["error"|"warn", {"preventAtEnd":false}] +// Message: Should be no multiple asterisks on middle lines. + +/** + * With a description + * @tag {SomeType} and a tag with details + ** + */ +// Message: Should be no multiple asterisks on middle lines. + +/** + ** + * + */ +// Message: Should be no multiple asterisks on middle lines. + +/** + * Desc. + * + **/ +// Message: Should be no multiple asterisks on end lines. + +/** + * Desc. + * + **/ +// "jsdoc/no-multi-asterisks": ["error"|"warn", {"preventAtEnd":true}] +// Message: Should be no multiple asterisks on end lines. + +/** + * Desc. + * + abc * **/ +// "jsdoc/no-multi-asterisks": ["error"|"warn", {"preventAtEnd":true}] +// Message: Should be no multiple asterisks on end lines. + +/** + * Desc. + * + **/ +// "jsdoc/no-multi-asterisks": ["error"|"warn", {"preventAtMiddleLines":false}] +// Message: Should be no multiple asterisks on end lines. +```` + +The following patterns are not considered problems: + +````js +/** + * + * Desc. *** + */ + +/** + * Desc. *** + * + */ + +/** + * Desc. + * + * sth */ + +/** + ** + * + */ +// "jsdoc/no-multi-asterisks": ["error"|"warn", {"preventAtMiddleLines":false}] + +/** + * + * + **/ +// "jsdoc/no-multi-asterisks": ["error"|"warn", {"preventAtEnd":false}] + +/** + * With a desc. + * and *** + */ + +/** + * and *** + * With a desc. + */ + +/** + * With a desc. + * With a desc. + * Desc. */ + +/** + * With a description + * @tag {SomeType} and a tag with details + * + */ +```` + + ### no-restricted-syntax @@ -8103,10 +8265,10 @@ structures, (whether or not you add a specific `comment` condition). Note that if your parser supports comment AST (as [jsdoc-eslint-parser/](https://github.com/brettz9/jsdoc-eslint-parser/) is designed to do), you can just use ESLint's rule. - + #### Options - + ##### contexts Set this to an array of strings representing the AST context (or an object with @@ -8207,10 +8369,10 @@ This rule reports types being used on `@param` or `@returns`. The rule is intended to prevent the indication of types on tags where the type information would be redundant with TypeScript. - + #### Options - + ##### contexts Set this to an array of strings representing the AST context (or an object with @@ -8380,7 +8542,7 @@ reporting on use of that namepath elsewhere) and/or that a tag's `type` is `false` (and should not be checked for types). If the `type` is an array, that array's items will be considered as defined for the purposes of that tag. - + #### Options An option object may have the following key: @@ -8935,7 +9097,7 @@ class Test { Requires that each JSDoc line starts with an `*`. - + #### Options This rule allows an optional string argument. If it is `"always"` then a @@ -8946,7 +9108,7 @@ and use the `tags` option to apply to specific tags only. After the string option, one may add an object with the following. - + ##### tags If you want different values to apply to specific tags, you may use @@ -9220,10 +9382,10 @@ Requires that block description, explicit `@description`, and * Periods after items within the `abbreviations` option array are not treated as sentence endings. - + #### Options - + ##### tags If you want additional tags to be checked for their descriptions, you may @@ -9247,14 +9409,14 @@ its "description" (e.g., for `@returns {someType} some description`, the description is `some description` while for `@some-tag xyz`, the description is `xyz`). - + ##### abbreviations You can provide an `abbreviations` options array to avoid such strings of text being treated as sentence endings when followed by dots. The `.` is not necessary at the end of the array items. - + ##### newlineBeforeCapsAssumesBadSentenceEnd When `false` (the new default), we will not assume capital letters after @@ -9925,7 +10087,7 @@ Requires that all functions have a description. is `"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: @@ -10450,12 +10612,12 @@ Requires that all functions have examples. * 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 @@ -10464,13 +10626,13 @@ block avoids the need for an `@example`. Defaults to an array with so be sure to add back `inheritdoc` if you wish its presence to cause exemption of the rule. - + ##### exemptNoArguments Boolean to indicate that no-argument functions should not be reported for missing `@example` declarations. - + ##### contexts Set this to an array of strings representing the AST context (or an object with @@ -10482,18 +10644,18 @@ want the rule to apply to any jsdoc block throughout your files. See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. - + ##### checkConstructors A value indicating whether `constructor`s should be checked. Defaults to `true`. - + ##### checkGetters A value indicating whether getters should be checked. Defaults to `false`. - + ##### checkSetters A value indicating whether setters should be checked. Defaults to `false`. @@ -10785,10 +10947,10 @@ Checks that: as being when the overview tag is not preceded by anything other than a comment. - + #### Options - + ##### tags The keys of this object are tag names, and the values are configuration @@ -11071,7 +11233,7 @@ function quux () { Requires (or disallows) a hyphen before the `@param` description. - + #### Options This rule takes one optional string argument and an optional options object. @@ -11302,12 +11464,12 @@ function main(argv) { Checks for presence of jsdoc comments, on class declarations as well as functions. - + #### Options Accepts one optional options object with the following optional keys. - + ##### publicOnly This option will insist that missing jsdoc blocks are only reported for @@ -11323,7 +11485,7 @@ otherwise noted): - `cjs` - CommonJS exports are checked for JSDoc comments (Defaults to `true`) - `window` - Window global exports are checked for JSDoc comments - + ##### require An object with the following optional boolean keys which all default to @@ -11336,7 +11498,7 @@ An object with the following optional boolean keys which all default to - `FunctionExpression` - `MethodDefinition` - + ##### contexts Set this to an array of strings or objects representing the additional AST @@ -11352,7 +11514,7 @@ if you are specifying a more precise form in `contexts` (e.g., `MethodDefinition See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. - + ##### exemptEmptyConstructors Default: true @@ -11361,7 +11523,7 @@ When `true`, the rule will not report missing jsdoc blocks above constructors with no parameters or return values (this is enabled by default as the class name or description should be seen as sufficient to convey intent). - + ##### exemptEmptyFunctions Default: false. @@ -11370,14 +11532,14 @@ When `true`, the rule will not report missing jsdoc blocks above functions/methods with no parameters or return values (intended where function/method names are sufficient for themselves as documentation). - + ##### checkConstructors A value indicating whether `constructor`s should be checked. Defaults to `true`. When `true`, `exemptEmptyConstructors` may still avoid reporting when no parameters or return values are found. - + ##### checkGetters A value indicating whether getters should be checked. Besides setting as a @@ -11386,7 +11548,7 @@ getters should be checked but only when there is no setter. This may be useful if one only wishes documentation on one of the two accessors. Defaults to `false`. - + ##### checkSetters A value indicating whether setters should be checked. Besides setting as a @@ -11395,7 +11557,7 @@ setters should be checked but only when there is no getter. This may be useful if one only wishes documentation on one of the two accessors. Defaults to `false`. - + ##### enableFixer A boolean on whether to enable the fixer (which adds an empty jsdoc block). @@ -12924,10 +13086,10 @@ export class User { Requires that each `@param` tag has a `description` value. - + #### Options - + ##### contexts Set this to an array of strings representing the AST context (or an object with @@ -13048,10 +13210,10 @@ Requires that all function parameters have names. > > [JSDoc](https://jsdoc.app/tags-param.html#overview) - + #### Options - + ##### contexts Set this to an array of strings representing the AST context (or an object with @@ -13184,10 +13346,10 @@ function example(cb) { Requires that each `@param` tag has a `type` value. - + #### Options - + ##### contexts Set this to an array of strings representing the AST context (or an object with @@ -13485,30 +13647,30 @@ other properties, so in looking at the docs alone without looking at the function signature, it may appear that there is an actual property named `extra`. - + #### Options An options object accepts the following optional properties: - + ##### enableFixer Whether to enable the fixer. Defaults to `true`. - + ##### enableRootFixer Whether to enable the auto-adding of incrementing roots (see the "Fixer" section). Defaults to `true`. Has no effect if `enableFixer` is set to `false`. - + ##### enableRestElementFixer Whether to enable the rest element fixer (see "Rest Element (`RestElement`) insertions"). Defaults to `true`. - + ##### checkRestProperty If set to `true`, will report (and add fixer insertions) for missing rest @@ -13562,13 +13724,13 @@ function quux ({num, ...extra}) { } ``` - + ##### autoIncrementBase Numeric to indicate the number at which to begin auto-incrementing roots. Defaults to `0`. - + ##### unnamedRootBase An array of root names to use in the fixer when roots are missing. Defaults @@ -13594,7 +13756,7 @@ function quux ({foo}, [bar], {baz}) { */ ``` - + ##### exemptedBy Array of tags (e.g., `['type']`) whose presence on the document block @@ -13603,7 +13765,7 @@ avoids the need for a `@param`. Defaults to an array with so be sure to add back `inheritdoc` if you wish its presence to cause exemption of the rule. - + ##### checkTypesPattern When one specifies a type, unless it is of a generic type, like `object` @@ -13638,7 +13800,7 @@ You could set this regular expression to a more expansive list, or you could restrict it such that even types matching those strings would not need destructuring. - + ##### contexts Set this to an array of strings representing the AST context (or an object with @@ -13650,28 +13812,28 @@ which are checked. See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors) section of our README for more on the expected format. - + ##### checkConstructors A value indicating whether `constructor`s should be checked. Defaults to `true`. - + ##### checkGetters A value indicating whether getters should be checked. Defaults to `false`. - + ##### checkSetters A value indicating whether setters should be checked. Defaults to `false`. - + ##### checkDestructured Whether to require destructured properties. Defaults to `true`. - + ##### checkDestructuredRoots Whether to check the existence of a corresponding `@param` for root objects @@ -13684,7 +13846,7 @@ implied to be `false` (i.e., the inside of the roots will not be checked either, e.g., it will also not complain if `a` or `b` do not have their own documentation). Defaults to `true`. - + ##### useDefaultObjectProperties Set to `true` if you wish to expect documentation of properties on objects @@ -15287,7 +15449,7 @@ is set to `false` no non-`undefined` returned or resolved value is found. Will also report if multiple `@returns` tags are present. - + #### Options - `exemptAsync` - By default, functions which return a `Promise` that are not @@ -15814,10 +15976,10 @@ Requires that the `@returns` tag has a `description` value. The error will not be reported if the return value is `void` or `undefined` or if it is `Promise` or `Promise`. - + #### Options - + ##### contexts Set this to an array of strings representing the AST context (or an object with @@ -15970,10 +16132,10 @@ function quux () { Requires that `@returns` tag has `type` value. - + #### Options - + ##### contexts Set this to an array of strings representing the AST context (or an object with @@ -16093,7 +16255,7 @@ Requires that returns are documented. Will also report if multiple `@returns` tags are present. - + #### Options - `checkConstructors` - A value indicating whether `constructor`s should @@ -17114,7 +17276,7 @@ async function foo() { Requires that throw statements are documented. - + #### Options - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the @@ -17390,7 +17552,7 @@ Will also report if multiple `@yields` tags are present. See the `next`, `forceRequireNext`, and `nextWithGeneratorTag` options for an option to expect a non-standard `@next` tag. - + #### Options - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the @@ -18200,7 +18362,7 @@ function bodies. Will also report if multiple `@yields` tags are present. - + #### Options - `checkGeneratorsOnly` - Avoids checking the function body and merely insists @@ -18678,7 +18840,7 @@ function * quux (foo) { Enforces lines (or no lines) between tags. - + #### Options The first option is a single string set to "always" or "never" (defaults to @@ -18686,12 +18848,12 @@ The first option is a single string set to "always" or "never" (defaults to The second option is an object with the following optional properties. - + ##### count (defaults to 1) Use with "always" to indicate the number of lines to require be present. - + ##### noEndLines (defaults to false) Use with "always" to indicate the normal lines to be added after tags should @@ -18904,7 +19066,7 @@ for valid types (based on the tag's `type` value), and either portion checked for presence (based on `false` `name` or `type` values or their `required` value). See the setting for more details. - + #### Options - `allowEmptyNamepaths` (default: true) - Set to `false` to bulk disallow diff --git a/src/index.js b/src/index.js index 2966c1954..99886cb18 100644 --- a/src/index.js +++ b/src/index.js @@ -17,6 +17,7 @@ import newlineAfterDescription from './rules/newlineAfterDescription'; import noBadBlocks from './rules/noBadBlocks'; import noDefaults from './rules/noDefaults'; import noMissingSyntax from './rules/noMissingSyntax'; +import noMultiAsterisks from './rules/noMultiAsterisks'; import noRestrictedSyntax from './rules/noRestrictedSyntax'; import noTypes from './rules/noTypes'; import noUndefinedTypes from './rules/noUndefinedTypes'; @@ -69,6 +70,7 @@ export default { 'jsdoc/no-bad-blocks': 'off', 'jsdoc/no-defaults': 'off', 'jsdoc/no-missing-syntax': 'off', + 'jsdoc/no-multi-asterisks': 'warn', 'jsdoc/no-restricted-syntax': 'off', 'jsdoc/no-types': 'off', 'jsdoc/no-undefined-types': 'warn', @@ -119,6 +121,7 @@ export default { 'no-bad-blocks': noBadBlocks, 'no-defaults': noDefaults, 'no-missing-syntax': noMissingSyntax, + 'no-multi-asterisks': noMultiAsterisks, 'no-restricted-syntax': noRestrictedSyntax, 'no-types': noTypes, 'no-undefined-types': noUndefinedTypes, diff --git a/src/rules/noMultiAsterisks.js b/src/rules/noMultiAsterisks.js new file mode 100644 index 000000000..cd5220084 --- /dev/null +++ b/src/rules/noMultiAsterisks.js @@ -0,0 +1,93 @@ +import iterateJsdoc from '../iterateJsdoc'; + +const middleAsterisks = /^[* \t]+/u; +const endAsterisks = /((?:\*|(?: |\t))*)\*$/u; + +export default iterateJsdoc(({ + context, + jsdoc, + utils, +}) => { + const { + preventAtEnd = true, + preventAtMiddleLines = true, + } = context.options[0] || {}; + + jsdoc.source.some(({tokens, number}) => { + const { + delimiter, tag, name, type, description, end, + } = tokens; + if ( + preventAtMiddleLines && + !end && !tag && !type && !name && middleAsterisks.test(description) + ) { + const fix = () => { + tokens.description = description.replace(middleAsterisks, ''); + }; + utils.reportJSDoc( + 'Should be no multiple asterisks on middle lines.', + { + line: number, + }, + fix, + true, + ); + + return true; + } + + if (!preventAtEnd || !end) { + return false; + } + const endingAsterisksAndSpaces = (description + delimiter).match( + endAsterisks, + ); + + if ( + !endingAsterisksAndSpaces || + endingAsterisksAndSpaces[1] && !endingAsterisksAndSpaces[1].trim() + ) { + return false; + } + + const endFix = () => { + tokens.delimiter = ''; + tokens.description = (description + delimiter).replace(endAsterisks, ''); + }; + + utils.reportJSDoc( + 'Should be no multiple asterisks on end lines.', + { + line: number, + }, + endFix, + true, + ); + + return true; + }); +}, { + iterateAllJsdocs: true, + meta: { + docs: { + description: '', + url: 'https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-no-multi-asterisks', + }, + fixable: 'code', + schema: [ + { + additionalProperies: false, + properties: { + preventAtEnd: { + type: 'boolean', + }, + preventAtMiddleLines: { + type: 'boolean', + }, + }, + type: 'object', + }, + ], + type: 'suggestion', + }, +}); diff --git a/test/rules/assertions/noMultiAsterisks.js b/test/rules/assertions/noMultiAsterisks.js new file mode 100644 index 000000000..89aabada7 --- /dev/null +++ b/test/rules/assertions/noMultiAsterisks.js @@ -0,0 +1,264 @@ +export default { + invalid: [ + { + code: ` + /** + * + ** + */ + `, + errors: [{ + line: 4, + message: 'Should be no multiple asterisks on middle lines.', + }], + output: ` + /** + * + * + */ + `, + }, + { + code: ` + /** + * + ** + */ + `, + errors: [{ + line: 4, + message: 'Should be no multiple asterisks on middle lines.', + }], + options: [{ + preventAtMiddleLines: true, + }], + output: ` + /** + * + * + */ + `, + }, + { + code: ` + /** + * + ** + */ + `, + errors: [{ + line: 4, + message: 'Should be no multiple asterisks on middle lines.', + }], + options: [{ + preventAtEnd: false, + }], + output: ` + /** + * + * + */ + `, + }, + { + code: ` + /** + * With a description + * @tag {SomeType} and a tag with details + ** + */ + `, + errors: [{ + line: 5, + message: 'Should be no multiple asterisks on middle lines.', + }], + output: ` + /** + * With a description + * @tag {SomeType} and a tag with details + * + */ + `, + }, + { + code: ` + /** + ** + * + */ + `, + errors: [{ + line: 3, + message: 'Should be no multiple asterisks on middle lines.', + }], + output: ` + /** + * + * + */ + `, + }, + { + code: ` + /** + * Desc. + * + **/ + `, + errors: [{ + line: 5, + message: 'Should be no multiple asterisks on end lines.', + }], + output: ` + /** + * Desc. + * + */ + `, + }, + { + code: ` + /** + * Desc. + * + **/ + `, + errors: [{ + line: 5, + message: 'Should be no multiple asterisks on end lines.', + }], + options: [{ + preventAtEnd: true, + }], + output: ` + /** + * Desc. + * + */ + `, + }, + { + code: ` + /** + * Desc. + * + abc * **/ + `, + errors: [{ + line: 5, + message: 'Should be no multiple asterisks on end lines.', + }], + options: [{ + preventAtEnd: true, + }], + output: ` + /** + * Desc. + * + abc*/ + `, + }, + { + code: ` + /** + * Desc. + * + **/ + `, + errors: [{ + line: 5, + message: 'Should be no multiple asterisks on end lines.', + }], + options: [{ + preventAtMiddleLines: false, + }], + output: ` + /** + * Desc. + * + */ + `, + }, + ], + valid: [ + { + code: ` + /** + * + * Desc. *** + */ + `, + }, + { + code: ` + /** + * Desc. *** + * + */ + `, + }, + { + code: ` + /** + * Desc. + * + * sth */ + `, + }, + { + code: ` + /** + ** + * + */ + `, + options: [{ + preventAtMiddleLines: false, + }], + }, + { + code: ` + /** + * + * + **/ + `, + options: [{ + preventAtEnd: false, + }], + }, + { + code: ` + /** + * With a desc. + * and *** + */ + `, + }, + { + code: ` + /** + * and *** + * With a desc. + */ + `, + }, + { + code: ` + /** + * With a desc. + * With a desc. + * Desc. */ + `, + }, + { + code: ` + /** + * With a description + * @tag {SomeType} and a tag with details + * + */ + `, + }, + ], +}; diff --git a/test/rules/ruleNames.json b/test/rules/ruleNames.json index 4240808ec..fedd59333 100644 --- a/test/rules/ruleNames.json +++ b/test/rules/ruleNames.json @@ -18,6 +18,7 @@ "no-bad-blocks", "no-defaults", "no-missing-syntax", + "no-multi-asterisks", "no-restricted-syntax", "no-types", "no-undefined-types",