JSDoc @throwsによるエラードキュメント

@throwsによるエラーのドキュメント化

@throwsタグは、関数がどのエラーをどのような条件でスローするかをドキュメント化します。これはエラーを正しく処理する必要があるAPI消費者にとって重要です。

シグネチャの例

function transferFunds(
  fromAccount: string,
  toAccount: string,
  amount: number,
  currency?: string
): TransferResult

@throwsの構文

@throws {ErrorType} このエラーが発生する条件の説明。

エラードキュメントの整理

1. 可能性の高い順: 最も一般的なエラーを最初にリスト
2. 具体的に: 「バリデーションに失敗した場合」より「メール形式が無効な場合」が良い
3. 回復のヒントを含める: 可能な場合、エラーの修正方法を提案
4. カスタムエラー型: カスタムエラークラス名を参照し、開発者が具体的にキャッチできるようにする

非同期エラー処理

非同期関数の場合、@throwsは同期的なスローとPromiseの拒否の両方をドキュメント化します。同期的にスローされるエラー（引数バリデーションなど）と拒否を引き起こすエラー（ネットワーク障害など）を明確にします。