feat(tag-lines): add dropEndLines option; fixes gajus#847

.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.

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.
 
+<a name="user-content-eslint-plugin-jsdoc-rules-tag-lines-options-41-dropendlines-defaults-to-false"></a>
+<a name="eslint-plugin-jsdoc-rules-tag-lines-options-41-dropendlines-defaults-to-false"></a>
+##### <code>dropEndLines</code> (defaults to <code>false</code>)
+
+If defined, will drop end lines for the final tag only.
+
 <a name="user-content-eslint-plugin-jsdoc-rules-tag-lines-options-41-tags-default-to-empty-object"></a>
 <a name="eslint-plugin-jsdoc-rules-tag-lines-options-41-tags-default-to-empty-object"></a>
 ##### <code>tags</code> (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}]
 ````
 
 

src/rules/tagLines.js

@@ -9,13 +9,15 @@ export default iterateJsdoc(({
     alwaysNever = 'never',
     {
       count = 1,
+      dropEndLines = false,
       noEndLines = false,
       tags = {},
     } = {},
   ] = context.options;
 
   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',
           },

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,
+        },
+      ],
+    },
   ],
 };