TypeScriptインターフェースのTSDoc

TypeScriptインターフェースのドキュメント化

インターフェースはTypeScriptにおけるオブジェクトの形状を定義します。適切にドキュメント化されたインターフェースは、オブジェクトが何を表すか、いつ使用するか、各プロパティの意味を説明します。

シグネチャの例

interface PaginationOptions {
  page: number;
  limit: number;
  sortBy?: string;
  sortOrder?: "asc" | "desc";
  cursor?: string;
}

生成されるTSDoc

/**
 * ページネーションされたAPIクエリの設定オプション。
 *
 * @remarks
 * 大規模なデータセット（10,000レコード以上）にはカーソルベースの
 * ページネーションを使用してください。
 */

プロパティレベルのドキュメント

インターフェースの各プロパティは独自のJSDocコメントを持つことができます：

interface PaginationOptions {
  /** 1始まりのページ番号。 */
  page: number;
  /** ページあたりの最大アイテム数（1-100）。 */
  limit: number;
}

@remarksの使用

TSDocの@remarksタグは、簡潔な要約と詳細なドキュメントを分離します。API Extractorなどのツールはこれを使用して、クイックインフォポップアップに要約を表示しながらremarksセクションを非表示にします。