JSDoc @throws for Error Documentation

Documenting Errors with @throws

The @throws tag documents what errors a function can throw and under what conditions. This is critical for API consumers who need to handle errors correctly.

Example Signature

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

Generated JSDoc

/**
 * Transfers funds between two accounts.
 *
 * @param {string} fromAccount - The source account ID.
 * @param {string} toAccount - The destination account ID.
 * @param {number} amount - The amount to transfer (must be positive).
 * @param {string} [currency="USD"] - The ISO 4217 currency code.
 * @returns {TransferResult} The completed transfer receipt.
 *
 * @throws {InsufficientFundsError} If the source account balance is
 *   less than the transfer amount.
 * @throws {AccountNotFoundError} If either account ID does not exist.
 * @throws {CurrencyMismatchError} If the accounts use different
 *   currencies and conversion is not available.
 * @throws {ValidationError} If the amount is zero, negative, or
 *   exceeds the daily transfer limit.
 * @throws {RateLimitError} If too many transfers have been attempted
 *   in the current time window.
 */

@throws Syntax

@throws {ErrorType} Description of when this error occurs.

If no specific error type exists, use the generic Error:

@throws {Error} If the input is invalid.

Organizing Error Documentation

1. Order by likelihood: List the most common errors first
2. Be specific: "If the email format is invalid" is better than "If validation fails"
3. Include recovery hints: When possible, suggest how to fix the error
4. Custom error types: Reference your custom error class names so developers can catch them specifically

Async Error Handling

For async functions, @throws documents both synchronous throws and Promise rejections. Make it clear which errors are thrown synchronously (e.g., argument validation) versus which cause rejections (e.g., network failures).