TypeScriptジェネリック関数のTSDoc

ジェネリック型パラメータのドキュメント化

ジェネリック関数は、複数の型で動作する型パラメータを受け入れます。ドキュメントでは各型パラメータが何を表すか、どのような制約があるかを説明する必要があります。

シグネチャの例

function groupBy<T, K extends keyof T>(items: T[], key: K): Map<T[K], T[]>

生成されるTSDoc

/**
 * 指定されたキーの値で配列アイテムをグループ化します。
 *
 * @typeParam T - 配列内のアイテムの型。
 * @typeParam K - グループ化するTのキー。
 * @param items - グループ化するアイテムの配列。
 * @param key - アイテムをグループ化するプロパティ名。
 * @returns 指定プロパティのユニークな値をキーとし、
 *   その値を持つアイテムの配列を値とするMap。
 */

@typeParam vs @template

タグ	標準	使用場面
@typeParam	TSDoc	TSDoc規約を使用するTypeScriptプロジェクト
@template	JSDoc	JavaScriptプロジェクトまたはJSDocスタイルのTypeScript

制約のドキュメント化

型パラメータに制約（extends）がある場合は、説明でそれに言及します。

複数の型パラメータ

各型パラメータを独自の行に記載します。シグネチャに表示される順序で並べます。型パラメータ間に参照関係がある場合はその関係を説明します。