eslint-plugin-jsdoc 37.7.0 → 37.8.2

package/README.md

@@ -70,6 +70,7 @@ JSDoc linting rules for ESLint.
         * [`require-throws`](#eslint-plugin-jsdoc-rules-require-throws)
         * [`require-yields`](#eslint-plugin-jsdoc-rules-require-yields)
         * [`require-yields-check`](#eslint-plugin-jsdoc-rules-require-yields-check)
+        * [`sort-tags`](#eslint-plugin-jsdoc-rules-sort-tags)
         * [`tag-lines`](#eslint-plugin-jsdoc-rules-tag-lines)
         * [`valid-types`](#eslint-plugin-jsdoc-rules-valid-types)
 
@@ -4728,7 +4729,7 @@ number
 bigint
 string
 symbol
-object
+object (For TypeScript's sake, however, using `Object` when specifying child types on it like `Object<string, number>`)
 Array
 Function
 Date
@@ -4789,7 +4790,7 @@ the `valid-types` rule to report parsing errors.
 
 Why are `boolean`, `number` and `string` exempt from starting with a capital
 letter? Let's take `string` as an example. In Javascript, everything is an
-object. The string Object has prototypes for string functions such as
+object. The `String` object has prototypes for string functions such as
 `.toUpperCase()`.
 
 Fortunately we don't have to write `new String()` everywhere in our code.
@@ -4812,17 +4813,28 @@ new String('lard') // String {0: "l", 1: "a", 2: "r", 3: "d", length: 4}
 new String('lard') === 'lard' // false
 ```
 
-To make things more confusing, there are also object literals and object
-Objects. But object literals are still static Objects and object Objects are
-instantiated Objects. So an object primitive is still an object Object.
+To make things more confusing, there are also object literals (like `{}`) and
+`Object` objects. But object literals are still static `Object`s and `Object`
+objects are instantiated objects. So an object primitive is still an `Object`
+object.
 
 However, `Object.create(null)` objects are not `instanceof Object`, however, so
-in the case of this Object we lower-case to indicate possible support for
-these objects.
+in the case of such a plain object we lower-case to indicate possible support
+for these objects. Also, nowadays, TypeScript also discourages use of `Object`
+as a lone type. However, one additional complexity is that TypeScript allows and
+actually [currently requires](https://github.com/microsoft/TypeScript/issues/20555)
+`Object` (with the initial upper-case) if used in the syntax
+`Object.<keyType, valueType>` or `Object<keyType, valueType`, perhaps to
+adhere to what [JSDoc documents](https://jsdoc.app/tags-type.html).
+
+So, for optimal compatibility with TypeScript (especially since TypeScript
+tools can be used on plain JavaScript with JSDoc), we are now allowing this
+TypeScript approach by default.
 
 Basically, for primitives, we want to define the type as a primitive, because
 that's what we use in 99.9% of cases. For everything else, we use the type
-rather than the primitive. Otherwise it would all just be `{object}`.
+rather than the primitive. Otherwise it would all just be `{object}` (with the
+additional exception of the special case of `Object.<>` just mentioned).
 
 In short: It's not about consistency, rather about the 99.9% use case. (And
 some functions might not even support the objects if they are checking for
@@ -5456,6 +5468,30 @@ function quux (foo) {
 }
 // Settings: {"jsdoc":{"mode":"typescript","preferredTypes":{"object.<>":"Object"}}}
 // Message: Invalid JSDoc @param "foo" type "object"; prefer: "Object".
+
+/**
+ * @param {object.<string, number>} foo
+ */
+function quux (foo) {
+}
+// Settings: {"jsdoc":{"mode":"typescript","preferredTypes":{"Object":"object","object.<>":"Object<>","Object.<>":"Object<>","object<>":"Object<>"}}}
+// Message: Invalid JSDoc @param "foo" type "object"; prefer: "Object<>".
+
+/**
+ * @param {Object.<string, number>} foo
+ */
+function quux (foo) {
+}
+// Settings: {"jsdoc":{"mode":"typescript","preferredTypes":{"Object":"object","object.<>":"Object<>","Object.<>":"Object<>","object<>":"Object<>"}}}
+// Message: Invalid JSDoc @param "foo" type "Object"; prefer: "Object<>".
+
+/**
+ * @param {object<string, number>} foo
+ */
+function quux (foo) {
+}
+// Settings: {"jsdoc":{"mode":"typescript","preferredTypes":{"Object":"object","object.<>":"Object<>","Object.<>":"Object<>","object<>":"Object<>"}}}
+// Message: Invalid JSDoc @param "foo" type "object"; prefer: "Object<>".
 ````
 
 The following patterns are not considered problems:
@@ -5751,6 +5787,18 @@ function quux (foo) {
 
 }
 // Settings: {"jsdoc":{"mode":"typescript"}}
+
+/**
+ * @typedef {object} foo
+ */
+function a () {}
+// Settings: {"jsdoc":{"mode":"typescript","preferredTypes":{"Object":"object","object.<>":"Object<>","object<>":"Object<>"}}}
+
+/**
+ * @typedef {Object<string, number>} foo
+ */
+function a () {}
+// Settings: {"jsdoc":{"mode":"typescript","preferredTypes":{"Object":"object","object.<>":"Object<>","object<>":"Object<>"}}}
 ````
 
 
@@ -6129,6 +6177,12 @@ function quux () {
 }
 // Message: @abstract should be empty.
 
+/**
+ * @interface extra text
+ */
+// Settings: {"jsdoc":{"mode":"closure"}}
+// Message: @interface should be empty.
+
 class Test {
     /**
      * @abstract extra text
@@ -20009,12 +20063,349 @@ function * quux (foo) {
 ````
 
 
+<a name="eslint-plugin-jsdoc-rules-sort-tags"></a>
+### <code>sort-tags</code>
+
+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).)
+
+<a name="eslint-plugin-jsdoc-rules-sort-tags-options-40"></a>
+#### Options
+
+<a name="eslint-plugin-jsdoc-rules-sort-tags-options-40-tagsequence"></a>
+##### <code>tagSequence</code>
+
+An array of tag names indicating the preferred sequence for sorting tags.
+
+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).
+
+Defaults to the array below.
+
+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
+[
+  // Brief descriptions
+  'summary',
+  'typeSummary',
+
+  // Module/file-level
+  'module',
+  'exports',
+  'file',
+  'fileoverview',
+  'overview',
+
+  // Identifying (name, type)
+  'typedef',
+  'interface',
+  'record',
+  'template',
+  'name',
+  'kind',
+  'type',
+  'alias',
+  'external',
+  'host',
+  'callback',
+  'func',
+  'function',
+  'method',
+  'class',
+  'constructor',
+
+  // Relationships
+  'modifies',
+  'mixes',
+  'mixin',
+  'mixinClass',
+  'mixinFunction',
+  'namespace',
+  'borrows',
+  'constructs',
+  'lends',
+  'implements',
+  'requires',
+
+  // Long descriptions
+  'desc',
+  'description',
+  'classdesc',
+  'tutorial',
+  'copyright',
+  'license',
+
+  // Simple annotations
+  'const',
+  'constant',
+  'final',
+  'global',
+  'readonly',
+  'abstract',
+  'virtual',
+  'var',
+  'member',
+  'memberof',
+  'memberof!',
+  'inner',
+  'instance',
+  'inheritdoc',
+  'inheritDoc',
+  'override',
+  'hideconstructor',
+
+  // Core function/object info
+  'param',
+  'arg',
+  'argument',
+  'prop',
+  'property',
+  'return',
+  'returns',
+
+  // Important behavior details
+  'async',
+  'generator',
+  'default',
+  'defaultvalue',
+  'enum',
+  'augments',
+  'extends',
+  'throws',
+  'exception',
+  'yield',
+  'yields',
+  'event',
+  'fires',
+  'emits',
+  'listens',
+  'this',
+
+  // Access
+  'static',
+  'private',
+  'protected',
+  'public',
+  'access',
+  'package',
+
+  '-other',
+
+  // Supplementary descriptions
+  'see',
+  'example',
+
+  // METADATA
+
+  // Other Closure (undocumented) metadata
+  'closurePrimitive',
+  'customElement',
+  'expose',
+  'hidden',
+  'idGenerator',
+  'meaning',
+  'ngInject',
+  'owner',
+  'wizaction',
+
+  // Other Closure (documented) metadata
+  'define',
+  'dict',
+  'export',
+  'externs',
+  'implicitCast',
+  'noalias',
+  'nocollapse',
+  'nocompile',
+  'noinline',
+  'nosideeffects',
+  'polymer',
+  'polymerBehavior',
+  'preserve',
+  'struct',
+  'suppress',
+  'unrestricted',
+
+  // @homer0/prettier-plugin-jsdoc metadata
+  'category',
+
+  // Non-Closure metadata
+  'ignore',
+  'author',
+  'version',
+  'variation',
+  'since',
+  'deprecated',
+  'todo',
+];
+```
+
+<a name="eslint-plugin-jsdoc-rules-sort-tags-options-40-alphabetizeextras"></a>
+##### <code>alphabetizeExtras</code>
+
+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.
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|any|
+|Recommended|false|
+|Settings||
+|Options|`tagSequence`, `alphabetizeExtras`|
+
+The following patterns are considered problems:
+
+````js
+/**
+ * @returns {string}
+ * @param b
+ * @param a
+ */
+function quux () {}
+// Message: Tags are not in the prescribed order: summary, typeSummary, module, exports, file, fileoverview, overview, typedef, interface, record, template, name, kind, type, alias, external, host, callback, func, function, method, class, constructor, modifies, mixes, mixin, mixinClass, mixinFunction, namespace, borrows, constructs, lends, implements, requires, desc, description, classdesc, tutorial, copyright, license, const, constant, final, global, readonly, abstract, virtual, var, member, memberof, memberof!, inner, instance, inheritdoc, inheritDoc, override, hideconstructor, param, arg, argument, prop, property, return, returns, async, generator, default, defaultvalue, enum, augments, extends, throws, exception, yield, yields, event, fires, emits, listens, this, static, private, protected, public, access, package, -other, see, example, closurePrimitive, customElement, expose, hidden, idGenerator, meaning, ngInject, owner, wizaction, define, dict, export, externs, implicitCast, noalias, nocollapse, nocompile, noinline, nosideeffects, polymer, polymerBehavior, preserve, struct, suppress, unrestricted, category, ignore, author, version, variation, since, deprecated, todo
+
+/**
+ * Some description
+ * @returns {string}
+ * @param b
+ * @param a
+ */
+function quux () {}
+// Message: Tags are not in the prescribed order: summary, typeSummary, module, exports, file, fileoverview, overview, typedef, interface, record, template, name, kind, type, alias, external, host, callback, func, function, method, class, constructor, modifies, mixes, mixin, mixinClass, mixinFunction, namespace, borrows, constructs, lends, implements, requires, desc, description, classdesc, tutorial, copyright, license, const, constant, final, global, readonly, abstract, virtual, var, member, memberof, memberof!, inner, instance, inheritdoc, inheritDoc, override, hideconstructor, param, arg, argument, prop, property, return, returns, async, generator, default, defaultvalue, enum, augments, extends, throws, exception, yield, yields, event, fires, emits, listens, this, static, private, protected, public, access, package, -other, see, example, closurePrimitive, customElement, expose, hidden, idGenerator, meaning, ngInject, owner, wizaction, define, dict, export, externs, implicitCast, noalias, nocollapse, nocompile, noinline, nosideeffects, polymer, polymerBehavior, preserve, struct, suppress, unrestricted, category, ignore, author, version, variation, since, deprecated, todo
+
+/**
+ * @returns {string}
+ * @param b A long
+ *   description
+ * @param a
+ */
+function quux () {}
+// Message: Tags are not in the prescribed order: summary, typeSummary, module, exports, file, fileoverview, overview, typedef, interface, record, template, name, kind, type, alias, external, host, callback, func, function, method, class, constructor, modifies, mixes, mixin, mixinClass, mixinFunction, namespace, borrows, constructs, lends, implements, requires, desc, description, classdesc, tutorial, copyright, license, const, constant, final, global, readonly, abstract, virtual, var, member, memberof, memberof!, inner, instance, inheritdoc, inheritDoc, override, hideconstructor, param, arg, argument, prop, property, return, returns, async, generator, default, defaultvalue, enum, augments, extends, throws, exception, yield, yields, event, fires, emits, listens, this, static, private, protected, public, access, package, -other, see, example, closurePrimitive, customElement, expose, hidden, idGenerator, meaning, ngInject, owner, wizaction, define, dict, export, externs, implicitCast, noalias, nocollapse, nocompile, noinline, nosideeffects, polymer, polymerBehavior, preserve, struct, suppress, unrestricted, category, ignore, author, version, variation, since, deprecated, todo
+
+/**
+ * Some description
+ * @returns {string}
+ * @param b A long
+ *   description
+ * @param a
+ */
+function quux () {}
+// Message: Tags are not in the prescribed order: summary, typeSummary, module, exports, file, fileoverview, overview, typedef, interface, record, template, name, kind, type, alias, external, host, callback, func, function, method, class, constructor, modifies, mixes, mixin, mixinClass, mixinFunction, namespace, borrows, constructs, lends, implements, requires, desc, description, classdesc, tutorial, copyright, license, const, constant, final, global, readonly, abstract, virtual, var, member, memberof, memberof!, inner, instance, inheritdoc, inheritDoc, override, hideconstructor, param, arg, argument, prop, property, return, returns, async, generator, default, defaultvalue, enum, augments, extends, throws, exception, yield, yields, event, fires, emits, listens, this, static, private, protected, public, access, package, -other, see, example, closurePrimitive, customElement, expose, hidden, idGenerator, meaning, ngInject, owner, wizaction, define, dict, export, externs, implicitCast, noalias, nocollapse, nocompile, noinline, nosideeffects, polymer, polymerBehavior, preserve, struct, suppress, unrestricted, category, ignore, author, version, variation, since, deprecated, todo
+
+/**
+ * @param b A long
+ *   description
+ * @returns {string}
+ * @param a
+ */
+function quux () {}
+// Message: Tags are not in the prescribed order: summary, typeSummary, module, exports, file, fileoverview, overview, typedef, interface, record, template, name, kind, type, alias, external, host, callback, func, function, method, class, constructor, modifies, mixes, mixin, mixinClass, mixinFunction, namespace, borrows, constructs, lends, implements, requires, desc, description, classdesc, tutorial, copyright, license, const, constant, final, global, readonly, abstract, virtual, var, member, memberof, memberof!, inner, instance, inheritdoc, inheritDoc, override, hideconstructor, param, arg, argument, prop, property, return, returns, async, generator, default, defaultvalue, enum, augments, extends, throws, exception, yield, yields, event, fires, emits, listens, this, static, private, protected, public, access, package, -other, see, example, closurePrimitive, customElement, expose, hidden, idGenerator, meaning, ngInject, owner, wizaction, define, dict, export, externs, implicitCast, noalias, nocollapse, nocompile, noinline, nosideeffects, polymer, polymerBehavior, preserve, struct, suppress, unrestricted, category, ignore, author, version, variation, since, deprecated, todo
+
+/**
+ * @def
+ * @xyz
+ * @abc
+ */
+function quux () {}
+// "jsdoc/sort-tags": ["error"|"warn", {"alphabetizeExtras":true}]
+// Message: Tags are not in the prescribed order: summary, typeSummary, module, exports, file, fileoverview, overview, typedef, interface, record, template, name, kind, type, alias, external, host, callback, func, function, method, class, constructor, modifies, mixes, mixin, mixinClass, mixinFunction, namespace, borrows, constructs, lends, implements, requires, desc, description, classdesc, tutorial, copyright, license, const, constant, final, global, readonly, abstract, virtual, var, member, memberof, memberof!, inner, instance, inheritdoc, inheritDoc, override, hideconstructor, param, arg, argument, prop, property, return, returns, async, generator, default, defaultvalue, enum, augments, extends, throws, exception, yield, yields, event, fires, emits, listens, this, static, private, protected, public, access, package, -other, see, example, closurePrimitive, customElement, expose, hidden, idGenerator, meaning, ngInject, owner, wizaction, define, dict, export, externs, implicitCast, noalias, nocollapse, nocompile, noinline, nosideeffects, polymer, polymerBehavior, preserve, struct, suppress, unrestricted, category, ignore, author, version, variation, since, deprecated, todo
+
+/**
+ * @xyz
+ * @def
+ * @abc
+ */
+function quux () {}
+// "jsdoc/sort-tags": ["error"|"warn", {"tagSequence":["def","xyz","abc"]}]
+// Message: Tags are not in the prescribed order: def, xyz, abc
+
+/**
+ * @returns {string}
+ * @ignore
+ * @param b A long
+ *   description
+ * @param a
+ * @module
+ */
+function quux () {}
+// Message: Tags are not in the prescribed order: summary, typeSummary, module, exports, file, fileoverview, overview, typedef, interface, record, template, name, kind, type, alias, external, host, callback, func, function, method, class, constructor, modifies, mixes, mixin, mixinClass, mixinFunction, namespace, borrows, constructs, lends, implements, requires, desc, description, classdesc, tutorial, copyright, license, const, constant, final, global, readonly, abstract, virtual, var, member, memberof, memberof!, inner, instance, inheritdoc, inheritDoc, override, hideconstructor, param, arg, argument, prop, property, return, returns, async, generator, default, defaultvalue, enum, augments, extends, throws, exception, yield, yields, event, fires, emits, listens, this, static, private, protected, public, access, package, -other, see, example, closurePrimitive, customElement, expose, hidden, idGenerator, meaning, ngInject, owner, wizaction, define, dict, export, externs, implicitCast, noalias, nocollapse, nocompile, noinline, nosideeffects, polymer, polymerBehavior, preserve, struct, suppress, unrestricted, category, ignore, author, version, variation, since, deprecated, todo
+
+/**
+ * @xyz
+ * @abc
+ * @abc
+ * @def
+ * @xyz
+ */
+function quux () {}
+// "jsdoc/sort-tags": ["error"|"warn", {"alphabetizeExtras":true}]
+// Message: Tags are not in the prescribed order: summary, typeSummary, module, exports, file, fileoverview, overview, typedef, interface, record, template, name, kind, type, alias, external, host, callback, func, function, method, class, constructor, modifies, mixes, mixin, mixinClass, mixinFunction, namespace, borrows, constructs, lends, implements, requires, desc, description, classdesc, tutorial, copyright, license, const, constant, final, global, readonly, abstract, virtual, var, member, memberof, memberof!, inner, instance, inheritdoc, inheritDoc, override, hideconstructor, param, arg, argument, prop, property, return, returns, async, generator, default, defaultvalue, enum, augments, extends, throws, exception, yield, yields, event, fires, emits, listens, this, static, private, protected, public, access, package, -other, see, example, closurePrimitive, customElement, expose, hidden, idGenerator, meaning, ngInject, owner, wizaction, define, dict, export, externs, implicitCast, noalias, nocollapse, nocompile, noinline, nosideeffects, polymer, polymerBehavior, preserve, struct, suppress, unrestricted, category, ignore, author, version, variation, since, deprecated, todo
+
+/**
+ * @param b A long
+ *   description
+ * @module
+ */
+function quux () {}
+// Message: Tags are not in the prescribed order: summary, typeSummary, module, exports, file, fileoverview, overview, typedef, interface, record, template, name, kind, type, alias, external, host, callback, func, function, method, class, constructor, modifies, mixes, mixin, mixinClass, mixinFunction, namespace, borrows, constructs, lends, implements, requires, desc, description, classdesc, tutorial, copyright, license, const, constant, final, global, readonly, abstract, virtual, var, member, memberof, memberof!, inner, instance, inheritdoc, inheritDoc, override, hideconstructor, param, arg, argument, prop, property, return, returns, async, generator, default, defaultvalue, enum, augments, extends, throws, exception, yield, yields, event, fires, emits, listens, this, static, private, protected, public, access, package, -other, see, example, closurePrimitive, customElement, expose, hidden, idGenerator, meaning, ngInject, owner, wizaction, define, dict, export, externs, implicitCast, noalias, nocollapse, nocompile, noinline, nosideeffects, polymer, polymerBehavior, preserve, struct, suppress, unrestricted, category, ignore, author, version, variation, since, deprecated, todo
+````
+
+The following patterns are not considered problems:
+
+````js
+/**
+ * @param b
+ * @param a
+ * @returns {string}
+ */
+function quux () {}
+
+/**
+ * @abc
+ * @def
+ * @xyz
+ */
+function quux () {}
+// "jsdoc/sort-tags": ["error"|"warn", {"alphabetizeExtras":true}]
+
+/**
+ * @def
+ * @xyz
+ * @abc
+ */
+function quux () {}
+// "jsdoc/sort-tags": ["error"|"warn", {"alphabetizeExtras":false}]
+
+/**
+ * @def
+ * @xyz
+ * @abc
+ */
+function quux () {}
+// "jsdoc/sort-tags": ["error"|"warn", {"tagSequence":["def","xyz","abc"]}]
+
+/** @def */
+function quux () {}
+````
+
+
 <a name="eslint-plugin-jsdoc-rules-tag-lines"></a>
 ### <code>tag-lines</code>
 
 Enforces lines (or no lines) between tags.
 
-<a name="eslint-plugin-jsdoc-rules-tag-lines-options-40"></a>
+<a name="eslint-plugin-jsdoc-rules-tag-lines-options-41"></a>
 #### Options
 
 The first option is a single string set to "always", "never", or "any"
@@ -20025,18 +20416,18 @@ for particular tags).
 
 The second option is an object with the following optional properties.
 
-<a name="eslint-plugin-jsdoc-rules-tag-lines-options-40-count-defaults-to-1"></a>
+<a name="eslint-plugin-jsdoc-rules-tag-lines-options-41-count-defaults-to-1"></a>
 ##### <code>count</code> (defaults to 1)
 
 Use with "always" to indicate the number of lines to require be present.
 
-<a name="eslint-plugin-jsdoc-rules-tag-lines-options-40-noendlines-defaults-to-false"></a>
+<a name="eslint-plugin-jsdoc-rules-tag-lines-options-41-noendlines-defaults-to-false"></a>
 ##### <code>noEndLines</code> (defaults to <code>false</code>)
 
 Use with "always" to indicate the normal lines to be added after tags should
 not be added after the final tag.
 
-<a name="eslint-plugin-jsdoc-rules-tag-lines-options-40-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)
 
 Overrides the default behavior depending on specific tags.
@@ -20432,7 +20823,7 @@ for valid types (based on the tag's `type` value), and either portion checked
 for presence (based on `false` `name` or `type` values or their `required`
 value). See the setting for more details.
 
-<a name="eslint-plugin-jsdoc-rules-valid-types-options-41"></a>
+<a name="eslint-plugin-jsdoc-rules-valid-types-options-42"></a>
 #### Options
 
 - `allowEmptyNamepaths` (default: true) - Set to `false` to bulk disallow

package/dist/defaultTagOrder.js

@@ -0,0 +1,26 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+const defaultTagOrder = [// Brief descriptions
+'summary', 'typeSummary', // Module/file-level
+'module', 'exports', 'file', 'fileoverview', 'overview', // Identifying (name, type)
+'typedef', 'interface', 'record', 'template', 'name', 'kind', 'type', 'alias', 'external', 'host', 'callback', 'func', 'function', 'method', 'class', 'constructor', // Relationships
+'modifies', 'mixes', 'mixin', 'mixinClass', 'mixinFunction', 'namespace', 'borrows', 'constructs', 'lends', 'implements', 'requires', // Long descriptions
+'desc', 'description', 'classdesc', 'tutorial', 'copyright', 'license', // Simple annotations
+'const', 'constant', 'final', 'global', 'readonly', 'abstract', 'virtual', 'var', 'member', 'memberof', 'memberof!', 'inner', 'instance', 'inheritdoc', 'inheritDoc', 'override', 'hideconstructor', // Core function/object info
+'param', 'arg', 'argument', 'prop', 'property', 'return', 'returns', // Important behavior details
+'async', 'generator', 'default', 'defaultvalue', 'enum', 'augments', 'extends', 'throws', 'exception', 'yield', 'yields', 'event', 'fires', 'emits', 'listens', 'this', // Access
+'static', 'private', 'protected', 'public', 'access', 'package', '-other', // Supplementary descriptions
+'see', 'example', // METADATA
+// Other Closure (undocumented) metadata
+'closurePrimitive', 'customElement', 'expose', 'hidden', 'idGenerator', 'meaning', 'ngInject', 'owner', 'wizaction', // Other Closure (documented) metadata
+'define', 'dict', 'export', 'externs', 'implicitCast', 'noalias', 'nocollapse', 'nocompile', 'noinline', 'nosideeffects', 'polymer', 'polymerBehavior', 'preserve', 'struct', 'suppress', 'unrestricted', // @homer0/prettier-plugin-jsdoc metadata
+'category', // Non-Closure metadata
+'ignore', 'author', 'version', 'variation', 'since', 'deprecated', 'todo'];
+var _default = defaultTagOrder;
+exports.default = _default;
+module.exports = exports.default;
+//# sourceMappingURL=defaultTagOrder.js.map

package/dist/defaultTagOrder.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/defaultTagOrder.js"],"names":["defaultTagOrder"],"mappings":";;;;;;AAAA,MAAMA,eAAe,GAAG,CACtB;AACA,SAFsB,EAGtB,aAHsB,EAKtB;AACA,QANsB,EAOtB,SAPsB,EAQtB,MARsB,EAStB,cATsB,EAUtB,UAVsB,EAYtB;AACA,SAbsB,EActB,WAdsB,EAetB,QAfsB,EAgBtB,UAhBsB,EAiBtB,MAjBsB,EAkBtB,MAlBsB,EAmBtB,MAnBsB,EAoBtB,OApBsB,EAqBtB,UArBsB,EAsBtB,MAtBsB,EAuBtB,UAvBsB,EAwBtB,MAxBsB,EAyBtB,UAzBsB,EA0BtB,QA1BsB,EA2BtB,OA3BsB,EA4BtB,aA5BsB,EA8BtB;AACA,UA/BsB,EAgCtB,OAhCsB,EAiCtB,OAjCsB,EAkCtB,YAlCsB,EAmCtB,eAnCsB,EAoCtB,WApCsB,EAqCtB,SArCsB,EAsCtB,YAtCsB,EAuCtB,OAvCsB,EAwCtB,YAxCsB,EAyCtB,UAzCsB,EA2CtB;AACA,MA5CsB,EA6CtB,aA7CsB,EA8CtB,WA9CsB,EA+CtB,UA/CsB,EAgDtB,WAhDsB,EAiDtB,SAjDsB,EAmDtB;AACA,OApDsB,EAqDtB,UArDsB,EAsDtB,OAtDsB,EAuDtB,QAvDsB,EAwDtB,UAxDsB,EAyDtB,UAzDsB,EA0DtB,SA1DsB,EA2DtB,KA3DsB,EA4DtB,QA5DsB,EA6DtB,UA7DsB,EA8DtB,WA9DsB,EA+DtB,OA/DsB,EAgEtB,UAhEsB,EAiEtB,YAjEsB,EAkEtB,YAlEsB,EAmEtB,UAnEsB,EAoEtB,iBApEsB,EAsEtB;AACA,OAvEsB,EAwEtB,KAxEsB,EAyEtB,UAzEsB,EA0EtB,MA1EsB,EA2EtB,UA3EsB,EA4EtB,QA5EsB,EA6EtB,SA7EsB,EA+EtB;AACA,OAhFsB,EAiFtB,WAjFsB,EAkFtB,SAlFsB,EAmFtB,cAnFsB,EAoFtB,MApFsB,EAqFtB,UArFsB,EAsFtB,SAtFsB,EAuFtB,QAvFsB,EAwFtB,WAxFsB,EAyFtB,OAzFsB,EA0FtB,QA1FsB,EA2FtB,OA3FsB,EA4FtB,OA5FsB,EA6FtB,OA7FsB,EA8FtB,SA9FsB,EA+FtB,MA/FsB,EAiGtB;AACA,QAlGsB,EAmGtB,SAnGsB,EAoGtB,WApGsB,EAqGtB,QArGsB,EAsGtB,QAtGsB,EAuGtB,SAvGsB,EAyGtB,QAzGsB,EA2GtB;AACA,KA5GsB,EA6GtB,SA7GsB,EA+GtB;AAEA;AACA,kBAlHsB,EAmHtB,eAnHsB,EAoHtB,QApHsB,EAqHtB,QArHsB,EAsHtB,aAtHsB,EAuHtB,SAvHsB,EAwHtB,UAxHsB,EAyHtB,OAzHsB,EA0HtB,WA1HsB,EA4HtB;AACA,QA7HsB,EA8HtB,MA9HsB,EA+HtB,QA/HsB,EAgItB,SAhIsB,EAiItB,cAjIsB,EAkItB,SAlIsB,EAmItB,YAnIsB,EAoItB,WApIsB,EAqItB,UArIsB,EAsItB,eAtIsB,EAuItB,SAvIsB,EAwItB,iBAxIsB,EAyItB,UAzIsB,EA0ItB,QA1IsB,EA2ItB,UA3IsB,EA4ItB,cA5IsB,EA8ItB;AACA,UA/IsB,EAiJtB;AACA,QAlJsB,EAmJtB,QAnJsB,EAoJtB,SApJsB,EAqJtB,WArJsB,EAsJtB,OAtJsB,EAuJtB,YAvJsB,EAwJtB,MAxJsB,CAAxB;eA2JeA,e","sourcesContent":["const defaultTagOrder = [\n  // Brief descriptions\n  'summary',\n  'typeSummary',\n\n  // Module/file-level\n  'module',\n  'exports',\n  'file',\n  'fileoverview',\n  'overview',\n\n  // Identifying (name, type)\n  'typedef',\n  'interface',\n  'record',\n  'template',\n  'name',\n  'kind',\n  'type',\n  'alias',\n  'external',\n  'host',\n  'callback',\n  'func',\n  'function',\n  'method',\n  'class',\n  'constructor',\n\n  // Relationships\n  'modifies',\n  'mixes',\n  'mixin',\n  'mixinClass',\n  'mixinFunction',\n  'namespace',\n  'borrows',\n  'constructs',\n  'lends',\n  'implements',\n  'requires',\n\n  // Long descriptions\n  'desc',\n  'description',\n  'classdesc',\n  'tutorial',\n  'copyright',\n  'license',\n\n  // Simple annotations\n  'const',\n  'constant',\n  'final',\n  'global',\n  'readonly',\n  'abstract',\n  'virtual',\n  'var',\n  'member',\n  'memberof',\n  'memberof!',\n  'inner',\n  'instance',\n  'inheritdoc',\n  'inheritDoc',\n  'override',\n  'hideconstructor',\n\n  // Core function/object info\n  'param',\n  'arg',\n  'argument',\n  'prop',\n  'property',\n  'return',\n  'returns',\n\n  // Important behavior details\n  'async',\n  'generator',\n  'default',\n  'defaultvalue',\n  'enum',\n  'augments',\n  'extends',\n  'throws',\n  'exception',\n  'yield',\n  'yields',\n  'event',\n  'fires',\n  'emits',\n  'listens',\n  'this',\n\n  // Access\n  'static',\n  'private',\n  'protected',\n  'public',\n  'access',\n  'package',\n\n  '-other',\n\n  // Supplementary descriptions\n  'see',\n  'example',\n\n  // METADATA\n\n  // Other Closure (undocumented) metadata\n  'closurePrimitive',\n  'customElement',\n  'expose',\n  'hidden',\n  'idGenerator',\n  'meaning',\n  'ngInject',\n  'owner',\n  'wizaction',\n\n  // Other Closure (documented) metadata\n  'define',\n  'dict',\n  'export',\n  'externs',\n  'implicitCast',\n  'noalias',\n  'nocollapse',\n  'nocompile',\n  'noinline',\n  'nosideeffects',\n  'polymer',\n  'polymerBehavior',\n  'preserve',\n  'struct',\n  'suppress',\n  'unrestricted',\n\n  // @homer0/prettier-plugin-jsdoc metadata\n  'category',\n\n  // Non-Closure metadata\n  'ignore',\n  'author',\n  'version',\n  'variation',\n  'since',\n  'deprecated',\n  'todo',\n];\n\nexport default defaultTagOrder;\n"],"file":"defaultTagOrder.js"}

package/dist/getDefaultTagStructureForMode.js

@@ -10,6 +10,7 @@ const getDefaultTagStructureForMode = mode => {
   const isClosure = mode === 'closure';
   const isTypescript = mode === 'typescript';
   const isPermissive = mode === 'permissive';
+  const isJsdocOrPermissive = isJsdoc || isPermissive;
   const isJsdocOrTypescript = isJsdoc || isTypescript;
   const isTypescriptOrClosure = isTypescript || isClosure;
   const isClosureOrPermissive = isClosure || isPermissive;
@@ -53,7 +54,8 @@ const getDefaultTagStructureForMode = mode => {
   //   seems to require both, and as "namepath"'s
   ['nameContents', 'namepath-referencing'], // "namepath"
   ['typeOrNameRequired', true]])], ['callback', new Map([// Seems to require a "namepath" in the signature (with no
-  //   counter-examples)
+  //   counter-examples); TypeScript does not enforce but seems
+  //   problematic as not attached so presumably not useable without it
   ['nameContents', 'namepath-defining'], // "namepath"
   ['nameRequired', true]])], ['class', new Map([// Allows for "name"'s in signature, but indicated as optional
   ['nameContents', 'namepath-defining'], ['typeAllowed', true]])], ['const', new Map([// Allows for "name"'s in signature, but indicated as optional
@@ -151,10 +153,15 @@ const getDefaultTagStructureForMode = mode => {
   // "typeName"
   ['typeRequired', true]])], ['typedef', new Map([// Seems to require a "namepath" in the signature (with no
   //  counter-examples)
-  ['nameContents', 'namepath-defining'], // "namepath"
-  ['nameRequired', isJsdocTypescriptOrPermissive], // Has example showing curly brackets but not in doc signature
-  ['typeAllowed', true], // "namepath"
-  ['typeOrNameRequired', true]])], ['var', new Map([// Allows for "name"'s in signature, but indicated as optional
+  ['nameContents', 'namepath-defining'], // TypeScript may allow it to be dropped if followed by @property or @member;
+  //   also shown as missing in Closure
+  // "namepath"
+  ['nameRequired', isJsdocOrPermissive], // Is not `typeRequired` for TypeScript because it gives an error:
+  // JSDoc '@typedef' tag should either have a type annotation or be followed by '@property' or '@member' tags.
+  // Has example showing curly brackets but not in doc signature
+  ['typeAllowed', true], // TypeScript may allow it to be dropped if followed by @property or @member
+  // "namepath"
+  ['typeOrNameRequired', !isTypescript]])], ['var', new Map([// Allows for "name"'s in signature, but indicated as optional
   ['nameContents', 'namepath-defining'], // Has example showing curly brackets but not in doc signature
   ['typeAllowed', true]])], ['yields', new Map([// Shows curly brackets in the signature and in the examples
   ['typeAllowed', true]])], ['yield', new Map([// Shows curly brackets in the signature and in the examples