Suggestion: Generics and JSDoc

[kitsonk]

Related to both #2913 and #2916, it is great having support for JSDoc annotations. One thing that does make using TypeScript with JSDoc a little bit of a challenge is how to annotate Generics. You can supply a lot of information to a consumer of the API now, but if you have generics, the consumer might be left wondering "what is this generic used for, what should I pass?"

There doesn't seem to be an appropriate tag for it in JSDoc. I am suggesting that maybe @generic would be appropriate, where the generic is named like a param is named and the type annotation would be if the generic extends another type. For example:

/**
 * My generic function
 * @generic {string} T     Give me some generic goodness
 * @param   {T}      value Some sort of generic thing
 * @returns {T}            and I will just it back to you
 */
function foo<T extends string>(value: T): T {
  return value;
}

[weswigham]

Actually, the closure compiler specifies @template for generics. The closure compiler jsdoc support list is more complete than the use jsdoc site, from a type system perspective.

[kitsonk]

@weswigham thanks! Ok, then I suggest the following:

/**
 * My generic function
 * @param   {T} value Some sort of generic thing
 * @returns {T}       and I will just it back to you
 * @template    T     Give me some generic goodness
 */
function foo<T extends string>(value: T): T {
  return value;
}

The one limitation is that it @template doesn't seem to have a structure for narrowing the type of generic.

[RyanCavanaugh]

I'm working on JSDoc support now and will keep this in mind

[billti]

Note @RyanCavanaugh that the initial work @CyrusNajmabadi did already had support for the JsDoc @template tag (see 0cb45c5 ).

[NoelAbrahams]

@template already has a tracker #1178

[mhegazy]

indeed. thanks @NoelAbrahams