diff --git a/.README/rules/tag-lines.md b/.README/rules/tag-lines.md index db4771c4d..4d00a33d1 100644 --- a/.README/rules/tag-lines.md +++ b/.README/rules/tag-lines.md @@ -8,7 +8,7 @@ The first option is a single string set to "always", "never", or "any" (defaults to "never"). "any" is only useful with `tags` (allowing non-enforcement of lines except -for particular tags). +for particular tags) or with `dropEndLines`. The second option is an object with the following optional properties. @@ -21,6 +21,10 @@ Use with "always" to indicate the number of lines to require be present. Use with "always" to indicate the normal lines to be added after tags should not be added after the final tag. +##### `dropEndLines` (defaults to `false`) + +If defined, will drop end lines for the final tag only. + ##### `tags` (default to empty object) Overrides the default behavior depending on specific tags. diff --git a/README.md b/README.md index ecd6719dd..9a986a4f7 100644 --- a/README.md +++ b/README.md @@ -20695,7 +20695,7 @@ The first option is a single string set to "always", "never", or "any" (defaults to "never"). "any" is only useful with `tags` (allowing non-enforcement of lines except -for particular tags). +for particular tags) or with `dropEndLines`. The second option is an object with the following optional properties. @@ -20712,6 +20712,12 @@ Use with "always" to indicate the number of lines to require be present. Use with "always" to indicate the normal lines to be added after tags should not be added after the final tag. + + +##### dropEndLines (defaults to false) + +If defined, will drop end lines for the final tag only. + ##### tags (default to empty object) @@ -20869,6 +20875,20 @@ The following patterns are considered problems: */ // "jsdoc/tag-lines": ["error"|"warn", "always"] // Message: Expected 1 line between tags but found 0 + +/** + * Some description + * @param {string} a + * @param {string} b + * + * @returns {SomeType} An extended + * description. + * + * This is still part of `@returns`. + * + */ +// "jsdoc/tag-lines": ["error"|"warn", "any",{"dropEndLines":true}] +// Message: Expected no trailing lines ```` The following patterns are not considered problems: @@ -21026,6 +21046,18 @@ The following patterns are not considered problems: * */ // "jsdoc/tag-lines": ["error"|"warn", "always"] + +/** + * Some description + * @param {string} a + * @param {string} b + * + * @returns {SomeType} An extended + * description. + * + * This is still part of `@returns`. + */ +// "jsdoc/tag-lines": ["error"|"warn", "any",{"dropEndLines":true}] ```` diff --git a/src/rules/tagLines.js b/src/rules/tagLines.js index 532f9ca3c..95e4576c3 100644 --- a/src/rules/tagLines.js +++ b/src/rules/tagLines.js @@ -9,6 +9,7 @@ export default iterateJsdoc(({ alwaysNever = 'never', { count = 1, + dropEndLines = false, noEndLines = false, tags = {}, } = {}, @@ -16,6 +17,7 @@ export default iterateJsdoc(({ jsdoc.tags.some((tg, tagIdx) => { let lastTag; + let lastEmpty = null; let reportIndex = null; for (const [ @@ -41,8 +43,9 @@ export default iterateJsdoc(({ continue; } + const empty = !tag && !name && !type && !description; if ( - !tag && !name && !type && !description && !end && + empty && !end && (alwaysNever === 'never' || lastTag && tags[lastTag.slice(1)]?.lines === 'never' ) @@ -52,9 +55,29 @@ export default iterateJsdoc(({ continue; } + if (!end) { + lastEmpty = empty ? idx : null; + } + lastTag = tag; } + if (dropEndLines && lastEmpty !== null && tagIdx === jsdoc.tags.length - 1) { + const fixer = () => { + utils.removeTagItem(tagIdx, lastEmpty); + }; + + utils.reportJSDoc( + 'Expected no trailing lines', + { + line: tg.source[lastEmpty].number, + }, + fixer, + ); + + return true; + } + if (reportIndex !== null) { const fixer = () => { utils.removeTagItem(tagIdx, reportIndex); @@ -163,6 +186,9 @@ export default iterateJsdoc(({ count: { type: 'integer', }, + dropEndLines: { + type: 'boolean', + }, noEndLines: { type: 'boolean', }, diff --git a/test/rules/assertions/tagLines.js b/test/rules/assertions/tagLines.js index 614cb39b3..b49a0c571 100644 --- a/test/rules/assertions/tagLines.js +++ b/test/rules/assertions/tagLines.js @@ -460,6 +460,45 @@ export default { */ `, }, + { + code: ` + /** + * Some description + * @param {string} a + * @param {string} b + * + * @returns {SomeType} An extended + * description. + * + * This is still part of \`@returns\`. + * + */ + `, + errors: [ + { + line: 11, + message: 'Expected no trailing lines', + }, + ], + options: [ + 'any', + { + dropEndLines: true, + }, + ], + output: ` + /** + * Some description + * @param {string} a + * @param {string} b + * + * @returns {SomeType} An extended + * description. + * + * This is still part of \`@returns\`. + */ + `, + }, ], valid: [ { @@ -766,5 +805,25 @@ export default { 'always', ], }, + { + code: ` + /** + * Some description + * @param {string} a + * @param {string} b + * + * @returns {SomeType} An extended + * description. + * + * This is still part of \`@returns\`. + */ + `, + options: [ + 'any', + { + dropEndLines: true, + }, + ], + }, ], };