feat: allow specification of tag groups and lines between (and before and after) them and removal of whitespace within them; fixes #782

BREAKING CHANGE:

`tagSequence` array of string tags argument must be specified instead as array of `{tags: []}` objects, with each object representing groups which can gain optional whitespace between them; if none are needed, just put all tags into the array of a single `{tags: []}`

Author: brettz9

.README/rules/sort-tags.md

@@ -4,28 +4,48 @@ Sorts tags by a specified sequence according to tag name.
 
 (Default order originally inspired by [`@homer0/prettier-plugin-jsdoc`](https://github.com/homer0/packages/tree/main/packages/public/prettier-plugin-jsdoc).)
 
+Optionally allows adding line breaks between tag groups and/or between tags
+within a tag group.
+
+Please note: unless you are disabling reporting of line breaks, this rule
+should not be used with the default "never" or "always" options of
+`tag-lines` (a rule enabled by default with the recommended config) as
+that rule adds its own line breaks after tags and may interfere with any
+line break setting this rule will attempt to do when not disabled.
+
+You may, however, safely set the "any" option in that rule along with
+`startLines` and/or `endLines`.
+
 #### Options
 
 ##### `tagSequence`
 
-An array of tag names indicating the preferred sequence for sorting tags.
+An array of tag group objects indicating the preferred sequence for sorting tags.
+
+Each item in the array should be an object with a `tags` property set to an array
+of tag names.
 
 Tag names earlier in the list will be arranged first. The relative position of
 tags of the same name will not be changed.
 
-Tags not in the list will be sorted alphabetically at the end (or in place of
-the pseudo-tag `-other` placed within `tagSequence`) if `alphabetizeExtras` is
-enabled and in their order of appearance otherwise (so if you want all your
-tags alphabetized, supply an empty array with `alphabetizeExtras` enabled).
+Earlier groups will also be arranged before later groups, but with the added
+feature that additional line breaks may be added between (or before or after)
+such groups (depending on the setting of `linesBetween`).
+
+Tag names not in the list will be grouped together at the end. The pseudo-tag
+`-other` can be used to place them anywhere else if desired. The tags will be
+placed in their order of appearance, or alphabetized if `alphabetizeExtras`
+is enabled, see more below about that option.
 
-Defaults to the array below.
+Defaults to the array below (noting that it is just a single tag group with
+no lines between groups by default).
 
 Please note that this order is still experimental, so if you want to retain
 a fixed order that doesn't change into the future, supply your own
 `tagSequence`.
 
 ```js
-[
+[{tags: [
   // Brief descriptions
   'summary',
   'typeSummary',
@@ -178,7 +198,7 @@ a fixed order that doesn't change into the future, supply your own
   'since',
   'deprecated',
   'todo',
-];
+]}];
 ```
 
 ##### `alphabetizeExtras`
@@ -187,12 +207,34 @@ Defaults to `false`. Alphabetizes any items not within `tagSequence` after any
 items within `tagSequence` (or in place of the special `-other` pseudo-tag)
 are sorted.
 
+If you want all your tags alphabetized, you can supply an empty array for
+`tagSequence` along with setting this option to `true`.
+
+##### `linesBetween`
+
+Indicates the number of lines to be added between tag groups. Defaults to 1.
+Do not set to 0 or 2+ if you are using `tag-lines` and `"always"` and do not
+set to 1+ if you are using `tag-lines` and `"never"`.
+
+##### `reportTagGroupSpacing`
+
+Whether to enable reporting and fixing of line breaks between tag groups
+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.
+
+##### `reportIntraTagGroupSpacing`
+
+Whether to enable reporting and fixing of line breaks within tags of a given
+tag group. Defaults to `true` which will remove any line breaks at the end of
+such tags. Do not use with `true` if you are using `tag-lines` and `always`.
+
 |||
 |---|---|
 |Context|everywhere|
 |Tags|any|
 |Recommended|false|
 |Settings||
-|Options|`tagSequence`, `alphabetizeExtras`|
+|Options|`tagSequence`, `alphabetizeExtras`, `linesBetween`, `reportTagGroupSpacing`, `reportIntraTagGroupSpacing`|
 
 <!-- assertions sortTags -->