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

[octogonz]

trafficstars

In https://github.com/Microsoft/tsdoc/issues/8#issuecomment-424751850 @aciccarello wrote:

For a generic type definition, it can be helpful to document what the generic type is used for. Using @template was mentioned in some previous comments but I wonder if @typeparam would be better. Either way, I think this would be a good candidate for inclusion of the standard tags.

VS Code already has some support for @template and there has been a request for TypeDoc to support that as well (TypeStrong/typedoc#860). TypeDoc currently supports @typeparam T - Description and @param <T> - Description.

/**
 * Alias for array
 * 
 * @typeparam T - Type of objects the list contains
 */
type List<T> = Array<T>;

/**
 * Wrapper for an HTTP Response
 * @typeparam B - Response body
 * @param <H> - Headers
 */
interface HttpResponse<B, H> {
    body: B;
    headers: H;
    statusCode: number;
}

[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.

[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.

[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 https://github.com/microsoft/web-build-tools/pull/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]

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:

[rbuckton]

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