Clarification on doc specification for parsing purposes

[brettz9]

Hi,

I've been working with eslint-plugin-jsdoc , jsdoctypeparser, and a little with comment-parser to better provide parsing tools which can report problems in one's jsdoc (or TypeScript or Closure doc) syntax.

(Btw, FWIW, @hegemonic , you or your team would be most welcome to join eslint-plugin-jsdoc or jsodoctypeparser, perhaps especially the latter may be of interest.)

It would be tremendously helpful to us if the following points could be clarified, and ideally added to the documentation. They're based on a fairly comprehensive review of items pertinent to parsing, at least based on the documentation. This might take some time to review, but I think it could really benefit the whole jsdoc/TypeScript/Closure community to have these formally answered and ideally documented.

Allowable custom tag names

Your source seems to allow any non-whitespace character \S to comprise a tag. Is this indeed intentional, or is this just to be forgiving for documentation purposes?

@extends {type}

Although you have @augments as the main tag, since it references @extends, you might mention that Closure only seems to allow @extends and also with an apparently required bracketed type.

@typedef {type} (Closure)

Closure allows a @typedef with no name, and pointing only to a (required) type for which mention could be made in the docs. See https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#typedef-type .

Access modifying Closure tags with types

The @public and @static tags are not documented as allowing a type as with @package, @private, and @protected, though the jsdoc code seems to suggest @public can have a type (and though Closure does not list allowing it, I would think @static should allow one though the code nor Closure suggests this). The Closure docs do not seem to help here either (only @private is listed with a type in its example in the docs at github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler ).

Namepaths pointing to special "name"'s

Can a namepath always include links to a @module, @event, or @external, or are there limits (e.g., only pointing to events from within @listens, etc. and not within say the type portion of @param)? It seems that any place listing a "namepath" can point to any of these?

Types including namepaths

As I understand it, where a type is allowed, a namepath can always be added and where a namepath is allowed, non-namepath types are never allowed (which is why @typedef lists @namepath in its defining portion since it wouldn't want to allow arbitrary types here despite the fact that it is defining a "type").

Curly brackets

These questions are about whether curly brackets signal a type/typeExpression or their absence a name/namepath/OtherObjectPath.

1. All of the items which mention a "name" (including the special names, @external, @module, and @event), "namepath", or "OtherObjectPath" (i.e., @mixes)--whether defining or pointing to names/paths--seem to avoid explicitly allowing curly brackets in their name portion (actually @modifies might be an exception to this in its test example allowing curly brackets; though it doesn't have documentation currently indicating it should include a "name" or "namepath", I am guessing its docs (Document modifies #1709) would suggest that its argument should be one of these, possibly "namepath" for the most flexibility). If this pattern should hold, I would hope @modifies could be changed for consistency or at least that its proposed docs draw attention to this fact. If the pattern does not hold (if curly brackets are allowed in some cases for defining or pointing to name/namepaths only (and not other types)), I would hope they might be mentioned as such, at least in the namepath doc file if not within each tag's doc file.
2. On the other hand, for the tags referencing a "type" (or in the case of @implements and the Closure types (@package, @private, @protected), a "typeExpression")--whether defining or pointing to types--there seems to be variation in either the signature and/or examples on whether the curly brackets are expected:
   1. Show curly brackets in both signature and examples: @implements, @type, @returns/@return, @throws/@exception, @yields/@yield
   2. Show curly brackets in the example, but not in the signature (presumably a doc oversight): @enum, @member/@var, @typedef
   3. Does not show curly brackets in the signature or examples (presumably an oversight): @class/@constructor, @constant/@const
   4. Shows curly brackets in the signature, but there is no example present with them: @module, @namespace (and the closure forms of @package, @private, @protected)
   5. These have no signature (presumably an oversight), but show curly brackets in the examples: @param/@arg/@argument, @property/@prop

In this connection, I would be interested to know where curly brackets may be allowed yet are not documented as such? E.g., if one can add them to @augments despite this not referencing a type nor using curly brackets. I would also be interested to know if they may be omitted, e.g.,
(In some cases, like @throws, this would be ambiguous, as this may also take free form text, but e.g., could @implements or some other type-pointing tag omit the curly brackets when not creating potential ambiguity?)

Note too that Closure and possibly TypeScript seem to allow curly brackets where you do not make it fully clear based on the doc signatures or examples where you allow or not: enum, extends (though not augments which they don't support), const, this.

Categorization questions

Below is a division of categories. But first a clarification of what we are seeking about these categories:

1. Is the difference between "type" and "typeExpression" fully consistent (i.e., should "typeExpression" actually be listed in some cases where "type" is now listed or vice versa)? I would assume those defining types should not allow "typeExpression" but many of the others listed as "type" seem they should instead be "typeExpression", suggesting, e.g., that they can handle unions, etc.
2. Are the docs currently fully accurate as far as items listed below as "required" (vs. "optional") because of their not having square brackets around the expression and "optional" otherwise?
3. Which tags define a type/namepath and which merely point to one. This can help us, for example, to ensure that a user is only pointing to a "name", "namepath", or "type" which has been defined.

The categories are based mostly on how the docs make them appear, not what they necessarily should be.

Categories

1. "typeExpression" (required; pointing only): @implements; for Closure only @extends (see dedicated section above)
2. "typeExpression" (optional; pointing only): The Closure types (@package, @private, @protected) and presumably @public and @static as well if these are meant to include a (Closure?)-optional "typeExpression" (see the dedicated section above)
3. "type" (required; defining only): @type
4. "type" (required, pointing only -- Closure only): A @typedef with no name, and pointing only to a (required) type. (see dedicated section)
5. "type" (optionally pointing to a "type" only; see the "Curly brackets", item no. 2, above, excluding @type and @typdef which are instead categorized and referenced elsewhere in this present list.
6. special "name" (required; defining only - pointing is instead through an optional, accompanying @see): @external, @event
7. special "name" (required; pointing only (to a class name, #, optional "event:", and event "name")): @emits/@fires
8. special "name" (required; pointing only (to an event "name")): @listens
9. special "name" (optionally defining a "module name" (i.e., a name with an optional "module:" prefix) and optionally pointing to a "type"): @module
10. "name" (required): No tags seem to fall into this category.
11. "name" (optionally defining a "name" and optionally pointing to a "type"): @class/@constructor, @constant/@const, @member/@var, @namespace
12. "name" (optionally defining a "name" only): @function/@func/@method, @mixin, @interface (though the latter not even optionally with a "name" in Closure)
13. "namepath" (required defining "namepath" only): @name, @callback
14. "namepath" (required defining "namepath", optionally pointing to a "type" ): @typedef
15. "namepath" (required pointing to two different "namepath"'s): @borrows
16. "namepath" (required "namepath" only, though allowing partial namepath by a namepath ending with connecting symbols like "#"): @memberof, @memberof!
17. "namepath" (optionally pointing to a "namepath" only): @alias, @augments/@extends, @lends, @this; also @modifies unless it should instead be included, e.g., under "name" or "namepath (required)"
18. "namepath" (optionally pointing to a "namepath" or potentially a non-namepath only): @see (optionally with text and/or inline @link tags in its place), @link (optionally with a URL in its place)
19. "OtherObjectPath" (required pointing to "OtherObjectPath" only): @mixes

Additional references

• Definition in source of modifies
• PR that added modifies
• Closure docs