RFC: Support for @typeparam or @template for documenting generic parameters

[microsoft]

RFC: Support for @typeparam or @template for documenting generic parameters

[rbuckton]

Also, the Closure Annotated JavaScript syntax is @template T (1, 2), which is already supported by TypeScript for hover/quick-info comments in both JavaScript and TypeScript files:

But @typeParam (or even @typeparam) is not currently supported:

[MartynasZilinskas]

I used @template in previous codebases. I think the word came from c++.

@typeparam make more sense in TypeScript context.

[dschnare]

I like this idea, but usually I solve this by giving the template parameters a better name.

class MyClass<TValue> {
  public value: TValue
  constructor (value: TValue) {
    this.value = value
  }
}

But I imagine there will be scenarios where having documentation for template parameters would be useful.

I also found this in the TypeScript wiki: https://github.com/Microsoft/TypeScript/wiki/JsDoc-support-in-JavaScript#template

Looks like the compiler went with @template for this one.

[octogonz]

I like @typeparam since @template seems unclear, like it's maybe telling us that the entire declaration is a template class. Following TSDoc capitalization it would be @typeParam.

Official JSDoc doesn't support either, so maybe have some freedom to choose which tag to use.

The grammar should be pretty much identical to @param, so if there's a consensus, I can create a PR to add it to the library pretty easily.

[helmbold]

@dschnare I agree with you that type parameters should have meaningful names, especially if there is more than on of it. However, sometimes it makes sense to explain a type parameter.

For example I have a class with a render function, that can take differently shaped objects and that may not be obvious to the user of this class. Let me show an example:

class Example<Parameters> {
  ...
  render(paramters: Parameters) {
    ...
  }
}

Usage is like this:

const e = new Example<{a: number, b: string}>();
e.render({a: 123, b: 'test'})

If I could explain this parameter, it would improve my API.

/**
 * @typeparam Parameters Shape of the object containing variables for rendering the template,
 * e.g. `Example<{a: number, b: string}>`.
 */
class Example<Parameters> {
```

[octogonz]

FYI @rbuckton recently implemented support for @typeParam in API Extractor with PR microsoft/rushstack#1317.

[rbuckton]

Does TSDoc require camelCase capitalization for tags? The JSDoc syntax uses all lowercase:

• @classdesc
• @defaultvalue (synonym for @default)
• @fileoverview (synonym for @file)
• @inheritdoc
• etc.

[rbuckton]

I threw together a PR that adds support for synonyms so that @template could be used as well.