Options to validate descriptions more precisely based on the specific tag

[brettz9]

Note: This needs to be reviewed, as others not marked as such may have since been implemented.

This is a request for a rule to validate descriptions more precisely based on the tag.

While this would be a lot of work, here is one more immediate to-do:

• no-undefined-types might use the pattern of valid-types to check for types within tags recognized as having a type.
• Handle assorted other tags in rules like require-description, require-description-complete-sentence, and especially match-description (see below)

---

Ported from eslint/eslint#11043

When a JSDoc code comment has certain tags present elsewhere in a block (and which is not one of those covered by the function/class-based detection of the current behavior), a description that fails to match the regular expression of matchDescription (or equivalent separate config) should also be able to apply.

Note that some of these may now be possible in match-description, though perhaps these as possibilities may be made explicit there.

These tags should, as I see it, be comprised of:

• Flagging an object of potentially broad purpose calling for a description @module, @mixin, @namespace, @external/@host
• Though more specialized in some ways, @typedef, @event objects may also be of enough importance for a description
• @interface if present should call for a description, particularly when within virtual comments where the lack of an associated function or class would necessitate its own warning
• While these may or may not be of general interest, they are generic enough that they may merit requiring a description as well: @global, @kind and @type
• @variation, @version, and @since, though more concrete, typically are associated with documentation as well

Besides certain tags flagging the need for a description by their presence, certain other tags require a description and I think there should be an option for matchDescription to match within these tags.

• @summary and @file/@fileoverview/@overview, fields which are descriptive in content and broad in purpose
• While the current code checks classes, I'm not sure whether @classdesc can occur separately from a class, e.g., as its own separate comment, and if so, its text should also be queryable.
• Some additional fields, though fairly specialized, like @copyright, @example, @see, @todo also have descriptive text areas which should never or rarely be empty; @throws/@exception, @yields/@yield and @property/@prop do likewise along with a possible type (and @property/@prop with a name as well)
• @deprecated might be better filled (to point to a replacement)
• allows free form text but really shouldn't be empty (@throws, @exception)

Other tags may expect something additional and would be worthy of having a rule, but are less like "descriptions":

• @author (with name and email; partly implemented but could allow checking against package.json contributors and author fields)
• a concrete technical name (@class (optional), @constructs (optional)); @event or @fires/@emits or @listens (<className>#[event:]<eventName>), @exports, @external/@host, @function (optional), @interface, @mixin, @requires
• a choice of names (@kind) feat(check-values): add checking of kind #837
• a type @enum (optional), @implements; @package (for Closure only), @private (for Closure only), @protected (for Closure only); not @public or @static for Closure?; @throws/@exception, @type, @typedef (type and name path))
• a type and name (@constant/@const (optional), @member/@var, @module, @namespace)
• a name path (@alias, @augments/@extends, @borrows (namepath "as" namepath), @callback, @lends, @memberof, @mixes, @name, @see, @this, @tutorial)
• a value (@default/@defaultvalue) Lint default param/property values and @default/@defaultvalue #473
• a version or identifier (@license, @since, @version)
• a status (@access (package|private|protected|public)
• a link (@link/@linkcode/@linkplain)
• inline identifier reference (block and inline @tutorial should point to config file tutorial IDs)

...and thus seem less like "descriptions" as per the rule name under discussion).

And a few seem they might benefit from insisting on no description as they don't seem to allow it:

• @abstract ,@async, @generator, @global, @hideconstructor, @ignore, @inheritdoc, @inner, @instance, @override, @readonly (and see access types above referencing Closure under types above)

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[JoernBerkefeld]

as a matter of fact, using {@link myMethod} breaks if it references a method from another class and complains about the incorrect reference. Meanwhile, vscode's intellisense can read those statements just fine.

I'm using that a lot lately when I create helper methods to link back to the main method in the description part of the jsdoc

[alystair]

I was hoping I could define text content in structuredTags to validate against sets of specific strings instead of types. Ex. "edition":{ "value": ["CORE","PRO","PLAT"] }, or specify no text/type content beyond the tag itself.

[brettz9]

For validating against specific strings, you can use match-description with the tags option, using a regex instead, e.g.:

'jsdoc/match-description': ['error', {tags: {edition: '^(?:CORE|PRO|PLAT)$'}}]

Regarding tags with no text/type content beyond the tag itself, you can use empty-tags with the tags option (or structuredTags with name: false and type: false).

[alystair]

Thanks I'll use that approach for now, however I think centralizing all custom tag config in the settings has merit. Esp. since they are otherwise split up between multiple rule sets. Ex. empty tags, check-tag-names, match-description...