Skip to content

Commit 38d51ff

Browse files
brettz9brettz9
committed
feat: add sort-tags rule
1 parent 9d0a75d commit 38d51ff

File tree

9 files changed

+1268
-7
lines changed

9 files changed

+1268
-7
lines changed

‎.README/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -589,5 +589,6 @@ selector).
589589
{"gitdown": "include", "file": "./rules/require-throws.md"}
590590
{"gitdown": "include", "file": "./rules/require-yields.md"}
591591
{"gitdown": "include", "file": "./rules/require-yields-check.md"}
592+
{"gitdown": "include", "file": "./rules/sort-tags.md"}
592593
{"gitdown": "include", "file": "./rules/tag-lines.md"}
593594
{"gitdown": "include", "file": "./rules/valid-types.md"}

‎.README/rules/sort-tags.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
### `sort-tags`
2+
3+
Sorts tags by a specified sequence according to tag name.
4+
5+
(Default order originally inspired by [`@homer0/prettier-plugin-jsdoc`](https://github.com/homer0/packages/tree/main/packages/public/prettier-plugin-jsdoc).)
6+
7+
#### Options
8+
9+
##### `tagSequence`
10+
11+
An array of tag names indicating the preferred sequence for sorting tags.
12+
13+
Tag names earlier in the list will be arranged first. The relative position of
14+
tags of the same name will not be changed.
15+
16+
Tags not in the list will be sorted alphabetically at the end (or in place of
17+
the pseudo-tag `-other` placed within `tagSequence`) if `alphabetizeExtras` is
18+
enabled and in their order of appearance otherwise (so if you want all your
19+
tags alphabetized, supply an empty array with `alphabetizeExtras` enabled).
20+
21+
Defaults to the array below.
22+
23+
Please note that this order is still experimental, so if you want to retain
24+
a fixed order that doesn't change into the future, supply your own
25+
`tagSequence`.
26+
27+
```js
28+
[
29+
// Brief descriptions
30+
'summary',
31+
'typeSummary',
32+
33+
// Module/file-level
34+
'module',
35+
'exports',
36+
'file',
37+
'fileoverview',
38+
'overview',
39+
40+
// Identifying (name, type)
41+
'typedef',
42+
'interface',
43+
'record',
44+
'template',
45+
'name',
46+
'kind',
47+
'type',
48+
'alias',
49+
'external',
50+
'host',
51+
'callback',
52+
'func',
53+
'function',
54+
'method',
55+
'class',
56+
'constructor',
57+
58+
// Relationships
59+
'modifies',
60+
'mixes',
61+
'mixin',
62+
'mixinClass',
63+
'mixinFunction',
64+
'namespace',
65+
'borrows',
66+
'constructs',
67+
'lends',
68+
'implements',
69+
'requires',
70+
71+
// Long descriptions
72+
'desc',
73+
'description',
74+
'classdesc',
75+
'tutorial',
76+
'copyright',
77+
'license',
78+
79+
// Simple annotations
80+
'const',
81+
'constant',
82+
'final',
83+
'global',
84+
'readonly',
85+
'abstract',
86+
'virtual',
87+
'var',
88+
'member',
89+
'memberof',
90+
'memberof!',
91+
'inner',
92+
'instance',
93+
'inheritdoc',
94+
'inheritDoc',
95+
'override',
96+
'hideconstructor',
97+
98+
// Core function/object info
99+
'param',
100+
'arg',
101+
'argument',
102+
'prop',
103+
'property',
104+
'return',
105+
'returns',
106+
107+
// Important behavior details
108+
'async',
109+
'generator',
110+
'default',
111+
'defaultvalue',
112+
'enum',
113+
'augments',
114+
'extends',
115+
'throws',
116+
'exception',
117+
'yield',
118+
'yields',
119+
'event',
120+
'fires',
121+
'emits',
122+
'listens',
123+
'this',
124+
125+
// Access
126+
'static',
127+
'private',
128+
'protected',
129+
'public',
130+
'access',
131+
'package',
132+
133+
'-other',
134+
135+
// Supplementary descriptions
136+
'see',
137+
'example',
138+
139+
// METADATA
140+
141+
// Other Closure (undocumented) metadata
142+
'closurePrimitive',
143+
'customElement',
144+
'expose',
145+
'hidden',
146+
'idGenerator',
147+
'meaning',
148+
'ngInject',
149+
'owner',
150+
'wizaction',
151+
152+
// Other Closure (documented) metadata
153+
'define',
154+
'dict',
155+
'export',
156+
'externs',
157+
'implicitCast',
158+
'noalias',
159+
'nocollapse',
160+
'nocompile',
161+
'noinline',
162+
'nosideeffects',
163+
'polymer',
164+
'polymerBehavior',
165+
'preserve',
166+
'struct',
167+
'suppress',
168+
'unrestricted',
169+
170+
// @homer0/prettier-plugin-jsdoc metadata
171+
'category',
172+
173+
// Non-Closure metadata
174+
'ignore',
175+
'author',
176+
'version',
177+
'variation',
178+
'since',
179+
'deprecated',
180+
'todo',
181+
];
182+
```
183+
184+
##### `alphabetizeExtras`
185+
186+
Defaults to `false`. Alphabetizes any items not within `tagSequence` after any
187+
items within `tagSequence` (or in place of the special `-other` pseudo-tag)
188+
are sorted.
189+
190+
|||
191+
|---|---|
192+
|Context|everywhere|
193+
|Tags|any|
194+
|Recommended|false|
195+
|Settings||
196+
|Options|`tagSequence`, `alphabetizeExtras`|
197+
198+
<!-- assertions sortTags -->

0 commit comments

Comments
 (0)