I replied to a new suggestion on an old issue suggesting a jsdoc tag for passing type arguments:
Our approach to JSDoc has evolved since this issue was created. At that time I didn’t want to add anything that didn’t have precedent in the jsdoc documentation generator, or at least in Closure compiler. However, Typescript is the largest processor of JSDoc at this point, and TS users who want typing are probably the most prolific authors of it. So we’ve decided on a few new principles:
@import is a good example, as is @overload. @enum is the worst counter-example I can think of, since it has Closure semantics.@alphanumeric.
b. Isn’t nested – starts at @ and continues till the next @.
c. Is used in a /** comment directly above a declaration. Both @import and @overload violate this, for good reasons.(1) means that TS users will be able to use the new JS syntax with a minimum of surprise. (2) means that jsdoc processors (including TS itself!) will be able to understand the new tag with a minimum of new parsing.
Re (2c), the rough descending order of goodness, or familiarity, in my opinion is:
/** comment directly preceding a declaration – like @type./** comment not connected to any JS syntax (which is to say, preceding some non-declaration) – like @import./** comment preceding an expression – like @type as a cast./** comment preceding another /** comment that eventually precedes a declaration – like @overload./** comment preceding some other, non-top-level node in the parse tree./*:: comment or some other new syntax.// @ts-alphanumeric comment preceding a declaration.