TypeScriptユーティリティ型とマップ型のTSDoc
TypeScriptユーティリティ型、マップ型、条件付き型のドキュメントを生成します。複雑な型レベル関数の@typeParamタグを解説します。
TypeScript
詳細な説明
ユーティリティ型とマップ型のドキュメント化
TypeScriptユーティリティ型は他の型に対して変換を実行します。型定義だけではロジックが明確でないことが多いため、ドキュメント化が重要です。
シグネチャの例
type DeepReadonly<T> = {
readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
};
生成されるTSDoc
/**
* Tのすべてのプロパティを再帰的にreadonlyにします。
*
* 組み込みの`Readonly<T>`はトップレベルのプロパティにのみ影響しますが、
* `DeepReadonly`はネストされたオブジェクトを走査して
* すべての深さレベルのプロパティを不変にします。
*
* @typeParam T - 深くreadonlyにするソース型。
*/
含めるべき内容
- 要約: 型が何をするか1文で
- 比較: 組み込みまたは類似の型との違い
- 型パラメータ: 各型パラメータが何を表すか
- 例: 型の実際の使用例
- 注意点: 循環参照、ユニオン型、プリミティブなどのエッジケース
ユースケース
共有型ユーティリティライブラリ、フレームワークレベルの型（ORMモデルトランスフォーマーなど）、再利用可能な型レベル関数を作成し明確な説明が必要なプロジェクトのドキュメント化。