Promiseを返す非同期関数のJSDoc

非同期関数のドキュメント化

非同期関数は常にPromiseを返します。JSDoc/TSDocコメントは、Promiseラッパーではなく解決値の型をドキュメント化する必要があります。@throwsを使用して潜在的な拒否理由もドキュメント化することが重要です。

シグネチャの例

async function fetchUser(id: string): Promise<User>

生成されるJSDoc

/**
 * APIからユニークな識別子でユーザーを取得します。
 *
 * @param {string} id - ユニークなユーザー識別子（UUID形式）。
 * @returns {Promise<User>} 見つかった場合のユーザーオブジェクト。
 * @throws {NotFoundError} 指定されたIDのユーザーが存在しない場合。
 * @throws {NetworkError} APIリクエストが失敗した場合。
 *
 * @example
 * ```typescript
 * const user = await fetchUser("abc-123");
 * console.log(user.name);
 * ```
 */

Promiseの拒否をドキュメント化する

非同期関数は複数の方法で拒否される可能性があります。各拒否理由にはそれぞれの@throwsタグが必要です：

• @throws {TypeError} — 無効な引数の場合
• @throws {NetworkError} — 接続の問題の場合
• @throws {NotFoundError} — リソースが見つからない場合

非同期 vs 同期のドキュメント

主な違いは戻り値の型です。非同期関数では、@returnsの型アノテーションに常にPromise<T>を含めてください。解決値の説明はPromiseを返すことではなく、Promiseが何に解決されるかを説明する必要があります。