feat(sort-tags): add tagExceptions to allow additional lines per tag; fixes #1594

Author: brettz9

.README/rules/sort-tags.md

@@ -36,7 +36,7 @@ adding line breaks between tag groups.
 |Tags|any|
 |Recommended|false|
 |Settings||
-|Options|`alphabetizeExtras`, `linesBetween`, `reportIntraTagGroupSpacing`, `reportTagGroupSpacing`, `tagSequence`|
+|Options|`alphabetizeExtras`, `linesBetween`, `reportIntraTagGroupSpacing`, `reportTagGroupSpacing`, `tagExceptions`, `tagSequence`|
 
 ## Failing examples
 

docs/rules/sort-tags.md

@@ -8,6 +8,7 @@
     * [`linesBetween`](#user-content-sort-tags-options-linesbetween)
     * [`reportIntraTagGroupSpacing`](#user-content-sort-tags-options-reportintrataggroupspacing)
     * [`reportTagGroupSpacing`](#user-content-sort-tags-options-reporttaggroupspacing)
+    * [`tagExceptions`](#user-content-sort-tags-options-tagexceptions)
     * [`tagSequence`](#user-content-sort-tags-options-tagsequence)
 * [Context and settings](#user-content-sort-tags-context-and-settings)
 * [Failing examples](#user-content-sort-tags-failing-examples)
@@ -80,6 +81,12 @@ as set by `linesBetween`. Defaults to `true`. Note that the very last tag
 will not have spacing applied regardless. For adding line breaks there, you
 may wish to use the `endLines` option of the `tag-lines` rule.
 
+<a name="user-content-sort-tags-options-tagexceptions"></a>
+<a name="sort-tags-options-tagexceptions"></a>
+### <code>tagExceptions</code>
+
+Allows specification by tag of a specific higher maximum number of lines. Keys are tags and values are the maximum number of lines allowed for such tags. Overrides `linesBetween`. Defaults to no special exceptions per tag.
+
 <a name="user-content-sort-tags-options-tagsequence"></a>
 <a name="sort-tags-options-tagsequence"></a>
 ### <code>tagSequence</code>
@@ -285,7 +292,7 @@ See description on `tagSequence`.
 |Tags|any|
 |Recommended|false|
 |Settings||
-|Options|`alphabetizeExtras`, `linesBetween`, `reportIntraTagGroupSpacing`, `reportTagGroupSpacing`, `tagSequence`|
+|Options|`alphabetizeExtras`, `linesBetween`, `reportIntraTagGroupSpacing`, `reportTagGroupSpacing`, `tagExceptions`, `tagSequence`|
 
 <a name="user-content-sort-tags-failing-examples"></a>
 <a name="sort-tags-failing-examples"></a>
@@ -531,6 +538,19 @@ function quux () {}
  */
 // "jsdoc/sort-tags": ["error"|"warn", {"tagSequence":[{"tags":["internal"]},{"tags":["template","param"]},{"tags":["returns"]},{"tags":["throws"]},{"tags":["see"]},{"tags":["example"]},{"tags":["since"]},{"tags":["deprecated"]}]}]
 // Message: Tag groups do not have the expected whitespace
+
+/**
+ * @param b
+ * @param a
+ * @returns {string}
+ * @example abc
+ *
+ *
+ * @example def
+ */
+function quux () {}
+// "jsdoc/sort-tags": ["error"|"warn", {"linesBetween":0,"tagExceptions":{"example":1}}]
+// Message: Intra-group tags have unexpected whitespace
 ````
 
 
@@ -651,5 +671,16 @@ function quux () {}
  */
 function quux () {}
 // "jsdoc/sort-tags": ["error"|"warn", {"linesBetween":2,"reportTagGroupSpacing":false,"tagSequence":[{"tags":["qrs"]},{"tags":["def","xyz"]},{"tags":["abc"]}]}]
+
+/**
+ * @param b
+ * @param a
+ * @returns {string}
+ * @example abc
+ *
+ * @example def
+ */
+function quux () {}
+// "jsdoc/sort-tags": ["error"|"warn", {"linesBetween":0,"tagExceptions":{"example":1}}]
 ````
 

src/rules.d.ts

@@ -2660,6 +2660,16 @@ export interface Rules {
            * may wish to use the `endLines` option of the `tag-lines` rule.
            */
           reportTagGroupSpacing?: boolean;
+          /**
+           * Allows specification by tag of a specific higher maximum number of lines. Keys are tags and values are the maximum number of lines allowed for such tags. Overrides `linesBetween`. Defaults to no special exceptions per tag.
+           */
+          tagExceptions?: {
+            /**
+             * This interface was referenced by `undefined`'s JSON-Schema definition
+             * via the `patternProperty` ".*".
+             */
+            [k: string]: number;
+          };
           /**
            * An array of tag group objects indicating the preferred sequence for sorting tags.
            *

src/rules/sortTags.js

@@ -5,11 +5,13 @@ export default iterateJsdoc(({
   context,
   jsdoc,
   utils,
+// eslint-disable-next-line complexity -- Temporary
 }) => {
   const
     /**
      * @type {{
      *   linesBetween: import('../iterateJsdoc.js').Integer,
+     *   tagExceptions: Record<string, number>,
      *   tagSequence: {
      *     tags: string[]
      *   }[],
@@ -22,6 +24,7 @@ export default iterateJsdoc(({
       linesBetween = 1,
       reportIntraTagGroupSpacing = true,
       reportTagGroupSpacing = true,
+      tagExceptions = {},
       tagSequence = defaultTagOrder,
     } = context.options[0] || {};
 
@@ -328,7 +331,7 @@ export default iterateJsdoc(({
       }
 
       const ct = countTagEmptyLines(tag);
-      if (ct) {
+      if (ct && (!tagExceptions[tag.tag] || tagExceptions[tag.tag] < ct)) {
         const fixer = () => {
           let foundFirstTag = false;
 
@@ -548,6 +551,15 @@ will not have spacing applied regardless. For adding line breaks there, you
 may wish to use the \`endLines\` option of the \`tag-lines\` rule.`,
             type: 'boolean',
           },
+          tagExceptions: {
+            description: 'Allows specification by tag of a specific higher maximum number of lines. Keys are tags and values are the maximum number of lines allowed for such tags. Overrides `linesBetween`. Defaults to no special exceptions per tag.',
+            patternProperties: {
+              '.*': {
+                type: 'number',
+              },
+            },
+            type: 'object',
+          },
           tagSequence: {
             description: `An array of tag group objects indicating the preferred sequence for sorting tags.
 

test/rules/assertions/sortTags.js

@@ -1461,6 +1461,45 @@ export default /** @type {import('../index.js').TestCases} */ ({
          */
       `,
     },
+    {
+      code: `
+        /**
+         * @param b
+         * @param a
+         * @returns {string}
+         * @example abc
+         *
+         *
+         * @example def
+         */
+        function quux () {}
+      `,
+      errors: [
+        {
+          line: 6,
+          message: 'Intra-group tags have unexpected whitespace',
+        },
+      ],
+      options: [
+        {
+          linesBetween: 0,
+          tagExceptions: {
+            example: 1,
+          },
+        },
+      ],
+      output: `
+        /**
+         * @param b
+         * @param a
+         * @returns {string}
+         * @example abc
+         *
+         * @example def
+         */
+        function quux () {}
+      `,
+    },
   ],
   valid: [
     {
@@ -1890,5 +1929,26 @@ export default /** @type {import('../index.js').TestCases} */ ({
         },
       ],
     },
+    {
+      code: `
+        /**
+         * @param b
+         * @param a
+         * @returns {string}
+         * @example abc
+         *
+         * @example def
+         */
+        function quux () {}
+      `,
+      options: [
+        {
+          linesBetween: 0,
+          tagExceptions: {
+            example: 1,
+          },
+        },
+      ],
+    },
   ],
 });