From 3aa4121341532c67091e794bc9150c7dc6b995f0 Mon Sep 17 00:00:00 2001 From: Brett Zamir Date: Wed, 29 Dec 2021 13:40:02 +0800 Subject: [PATCH] feat(`no-multi-asterisks`): add `allowWhitespace` option; fixes #803 --- .README/rules/no-multi-asterisks.md | 10 ++ README.md | 49 ++++++++++ src/rules/noMultiAsterisks.js | 38 ++++++-- test/rules/assertions/noMultiAsterisks.js | 111 ++++++++++++++++++++++ 4 files changed, 202 insertions(+), 6 deletions(-) diff --git a/.README/rules/no-multi-asterisks.md b/.README/rules/no-multi-asterisks.md index 3d30ea8b3..0dbbd0f7c 100644 --- a/.README/rules/no-multi-asterisks.md +++ b/.README/rules/no-multi-asterisks.md @@ -8,6 +8,16 @@ and that rule is for catching blocks which only seem like jsdoc). #### Options +##### `allowWhitespace` (defaults to `false`) + +Set to `true` if you wish to allow asterisks after a space (as with Markdown): + +```js +/** + * *bold* text + */ +``` + ##### `preventAtMiddleLines` (defaults to `true`) Prevent the likes of this: diff --git a/README.md b/README.md index c66cb5a0c..4c0351dd2 100644 --- a/README.md +++ b/README.md @@ -8712,6 +8712,17 @@ and that rule is for catching blocks which only seem like jsdoc). #### Options + +##### allowWhitespace (defaults to false) + +Set to `true` if you wish to allow asterisks after a space (as with Markdown): + +```js +/** + * *bold* text + */ +``` + ##### preventAtMiddleLines (defaults to true) @@ -8823,6 +8834,25 @@ The following patterns are considered problems: * */ // "jsdoc/no-multi-asterisks": ["error"|"warn", {"preventAtEnd":true}] // Message: Should be no multiple asterisks on end lines. + +/** + * The method does 2 things: + * * Thing 1 + * * Thing 2 + */ +// "jsdoc/no-multi-asterisks": ["error"|"warn", {"allowWhitespace":false}] +// Message: Should be no multiple asterisks on middle lines. + +/** + * This muti-line comment contains some + * *non-standard bold* syntax + */ +// "jsdoc/no-multi-asterisks": ["error"|"warn", {"allowWhitespace":false}] +// Message: Should be no multiple asterisks on middle lines. + +/** Desc. **/ +// "jsdoc/no-multi-asterisks": ["error"|"warn", {"allowWhitespace":true}] +// Message: Should be no multiple asterisks on end lines. ```` The following patterns are not considered problems: @@ -8900,6 +8930,25 @@ function foo() { * * **Bold example:** Hi there. */ + +/** + * The method does 2 things: + * * Thing 1 + * * Thing 2 + */ +// "jsdoc/no-multi-asterisks": ["error"|"warn", {"allowWhitespace":true}] + +/** + * This muti-line comment contains some + * *non-standard bold* syntax + */ +// "jsdoc/no-multi-asterisks": ["error"|"warn", {"allowWhitespace":true}] + +/** abc */ +function foo() { + // +} +// "jsdoc/no-multi-asterisks": ["error"|"warn", {"allowWhitespace":true}] ```` diff --git a/src/rules/noMultiAsterisks.js b/src/rules/noMultiAsterisks.js index 74e2f5e17..d2da3f134 100644 --- a/src/rules/noMultiAsterisks.js +++ b/src/rules/noMultiAsterisks.js @@ -1,6 +1,13 @@ import iterateJsdoc from '../iterateJsdoc'; -const middleAsterisks = /^([\t ]|\*(?!\*))+/u; +const middleAsterisksBlockWS = /^([\t ]|\*(?!\*))+/u; +const middleAsterisksNoBlockWS = /^\*+/u; + +const endAsterisksSingleLineBlockWS = /\*((?:\*|(?: |\t))*)\*$/u; +const endAsterisksMultipleLineBlockWS = /((?:\*|(?: |\t))*)\*$/u; + +const endAsterisksSingleLineNoBlockWS = /\*(\**)\*$/u; +const endAsterisksMultipleLineNoBlockWS = /(\**)\*$/u; export default iterateJsdoc(({ context, @@ -8,10 +15,14 @@ export default iterateJsdoc(({ utils, }) => { const { + allowWhitespace = false, preventAtEnd = true, preventAtMiddleLines = true, } = context.options[0] || {}; + const middleAsterisks = allowWhitespace ? middleAsterisksNoBlockWS : middleAsterisksBlockWS; + + // eslint-disable-next-line complexity -- Todo jsdoc.source.some(({ tokens, number, @@ -23,11 +34,18 @@ export default iterateJsdoc(({ type, description, end, + postDelimiter, } = tokens; + if ( preventAtMiddleLines && - !end && !tag && !type && !name && middleAsterisks.test(description) + !end && !tag && !type && !name && + ( + !allowWhitespace && middleAsterisks.test(description) || + allowWhitespace && middleAsterisks.test(postDelimiter + description) + ) ) { + // console.log('description', JSON.stringify(description)); const fix = () => { tokens.description = description.replace(middleAsterisks, ''); }; @@ -50,11 +68,16 @@ export default iterateJsdoc(({ const isSingleLineBlock = delimiter === '/**'; const delim = isSingleLineBlock ? '*' : delimiter; - const endAsterisks = isSingleLineBlock ? - /\*((?:\*|(?: |\t))*)\*$/u : - /((?:\*|(?: |\t))*)\*$/u; + let endAsterisks; + if (allowWhitespace) { + endAsterisks = isSingleLineBlock ? endAsterisksSingleLineNoBlockWS : endAsterisksMultipleLineNoBlockWS; + } else { + endAsterisks = isSingleLineBlock ? endAsterisksSingleLineBlockWS : endAsterisksMultipleLineBlockWS; + } - const endingAsterisksAndSpaces = (description + delim).match( + const endingAsterisksAndSpaces = ( + allowWhitespace ? postDelimiter + description + delim : description + delim + ).match( endAsterisks, ); @@ -96,6 +119,9 @@ export default iterateJsdoc(({ { additionalProperies: false, properties: { + allowWhitespace: { + type: 'boolean', + }, preventAtEnd: { type: 'boolean', }, diff --git a/test/rules/assertions/noMultiAsterisks.js b/test/rules/assertions/noMultiAsterisks.js index 0760e926e..a48ee517d 100644 --- a/test/rules/assertions/noMultiAsterisks.js +++ b/test/rules/assertions/noMultiAsterisks.js @@ -276,6 +276,77 @@ export default { */ `, }, + { + code: ` + /** + * The method does 2 things: + * * Thing 1 + * * Thing 2 + */ + `, + errors: [ + { + line: 4, + message: 'Should be no multiple asterisks on middle lines.', + }, + ], + options: [ + { + allowWhitespace: false, + }, + ], + output: ` + /** + * The method does 2 things: + * Thing 1 + * * Thing 2 + */ + `, + }, + { + code: ` + /** + * This muti-line comment contains some + * *non-standard bold* syntax + */ + `, + errors: [ + { + line: 4, + message: 'Should be no multiple asterisks on middle lines.', + }, + ], + options: [ + { + allowWhitespace: false, + }, + ], + output: ` + /** + * This muti-line comment contains some + * non-standard bold* syntax + */ + `, + }, + { + code: ` + /** Desc. **/ + `, + errors: [ + { + line: 2, + message: 'Should be no multiple asterisks on end lines.', + }, + ], + options: [ + { + allowWhitespace: true, + }, + ], + output: ` + /** Desc. */ + `, + }, ], valid: [ { @@ -402,5 +473,45 @@ export default { */ `, }, + { + code: ` + /** + * The method does 2 things: + * * Thing 1 + * * Thing 2 + */ + `, + options: [ + { + allowWhitespace: true, + }, + ], + }, + { + code: ` + /** + * This muti-line comment contains some + * *non-standard bold* syntax + */ + `, + options: [ + { + allowWhitespace: true, + }, + ], + }, + { + code: ` + /** abc */ + function foo() { + // + } + `, + options: [ + { + allowWhitespace: true, + }, + ], + }, ], };