tsdoc-comments

API コメントには TSDoc を使用する

概要

TSDoc は TypeScript コードのドキュメント作成における標準です。ジェネリック型パラメーター（@template）など、TypeScript 固有の機能を追加した JSDoc の拡張です。優れたドキュメントは、コードが何をするかだけでなく、なぜそうするのかを説明し、IDE のツールチップや生成されたドキュメントを通じて、ユーザーが API を理解できるようにします。

適切にドキュメント化されたコードは、サポートの負担を軽減し、API 利用者の開発者エクスペリエンスを向上させます。

このスキルを使用する場面

• 公開 API をドキュメント化する場合
• 他の人が使用するライブラリコードを書く場合
• 複雑な型パラメーターを説明する場合
• コードからドキュメントを生成する場合
• IDE のツールチップを提供する場合

絶対のルール

公開 API は TSDoc でドキュメント化します。何をするか、なぜそうするかを説明し、例を示します。ジェネリック型パラメーターには @template を使用します。

検出

ドキュメント化されていない公開 API に注意してください。

// RED FLAGS - Missing documentation
export function process(data: unknown): Result;  // What does it do?
export type Transform<T> = /* complex type */;   // What's T for?
export class ApiClient {                         // How do I use this?
  constructor(config: Config) {}
}

TSDoc の基本構造

/**
 * Short description of what this does.
 *
 * Longer explanation if needed. Explain why this exists,
 * when to use it, and any important caveats.
 *
 * @param paramName - Description of parameter
 * @returns Description of return value
 * @example
 * ```typescript
 * const result = myFunction('input');
 * console.log(result); // 'processed: input'
 * ```
 */
function myFunction(input: string): string {
  return `processed: ${input}`;
}

関数のドキュメント化

/**
 * Fetches user data from the API.
 *
 * Automatically handles authentication and retries failed requests
 * up to 3 times with exponential backoff.
 *
 * @param userId - The unique identifier for the user
 * @param options - Optional configuration for the request
 * @returns A promise that resolves to the user data
 * @throws {ApiError} When the user is not found or the request fails
 * @example
 * ```typescript
 * const user = await fetchUser('123');
 * console.log(user.name);
 * ```
 */
async function fetchUser(
  userId: string,
  options?: FetchOptions
): Promise<User> {
  // Implementation
}

ジェネリック型のドキュメント化

/**
 * Creates a partial version of a type where all properties are optional.
 *
 * @template T - The type to make partial
 * @example
 * ```typescript
 * interface User {
 *   name: string;
 *   age: number;
 * }
 *
 * type PartialUser = Partial<User>;
 * // { name?: string; age?: number; }
 * ```
 */
type MyPartial<T> = {
  [K in keyof T]?: T[K];
};

クラスのドキュメント化

/**
 * Client for interacting with the REST API.
 *
 * Handles authentication, request retries, and response parsing.
 * Create one instance per application and reuse it.
 *
 * @example
 * ```typescript
 * const client = new ApiClient({
 *   baseUrl: 'https://api.example.com',
 *   apiKey: process.env.API_KEY
 * });
 *
 * const users = await client.users.list();
 * ```
 */
export class ApiClient {
  /**
   * Creates a new API client instance.
   *
   * @param config - Configuration options for the client
   */
  constructor(config: ClientConfig) {}

  /**
   * Resources for managing users.
   */
  readonly users: UserResource;
}

よく使う TSDoc タグ

/**
 * Description of the function.
 *
 * @param name - Parameter description
 * @returns Return value description
 * @throws {ErrorType} When/why this error is thrown
 * @example Code example showing usage
 * @deprecated Use newFunction instead. Will be removed in v2.0.
 * @see Related function or documentation
 * @internal For internal use only, not part of public API
 */

// For generic types:
/**
 * @template T - Description of type parameter
 * @template K - Description of second parameter
 */

// For class members:
/**
 * @readonly This property is read-only
 * @protected This member is protected
 */

プレッシャー耐性プロトコル

コードをドキュメント化するときは、次の点に注意してください。

1. 公開 API をドキュメント化する：エクスポートされるものはすべてドキュメント化します
2. 何をするかだけでなく、なぜそうするかを説明する：ユーザーが適切な判断を下せるようにします
3. 例を示す：実際の使用パターンを示します
4. 例外をドキュメント化する：何が問題になり得るか、なぜそうなるかを説明します
5. 最新の状態に保つ：コードを変更したらドキュメントも更新します

注意すべき兆候

アンチパターン	問題	解決策
ドキュメントがない	ユーザーが使い方を推測することになる	TSDoc コメントを追加する
「自明な」コメント	// Adds 1 to x	何をするかではなく、なぜそうするかを説明する
古いドキュメント	ユーザーを誤解させる	コードの変更に合わせて更新する
@template がない	ジェネリック型が説明されていない	型パラメーターをドキュメント化する

よくある言い訳

「コードを見れば分かる」

実際には：コードで分かるのは何が起きるかであり、なぜそうなるかではありません。ドキュメントは意図と背景を説明します。

「後でドキュメントを書けばいい」

実際には：後で書くことはありません。背景を覚えているうちに、コードを書くのと同時にドキュメント化しましょう。

「内部コードにすぎない」

実際には：未来の自分や同僚もユーザーです。自明でないことは何でもドキュメント化しましょう。

クイックリファレンス

タグ	用途
@param	関数のパラメーター
@returns	戻り値の説明
@template	ジェネリック型パラメーター
@example	使用例
@throws	スローされる例外
@deprecated	非推奨の API を示す
@see	関連ドキュメント

要点

公開 API は TSDoc でドキュメント化します。関数が何をするか、なぜ存在するか、どのように使うかを説明しましょう。優れたドキュメントは IDE のツールチップに表示され、サポートの負担を軽減します。

参考資料

• Dan Vanderkam 著『Effective TypeScript』第 2 版
• 項目 68：API コメントには TSDoc を使用する