Intermediate Reading #library-docs #jsdoc #typescript

Reading Library Documentation

5 exercises on function signatures, JSDoc annotations, TypeScript types, return values, and Caveats sections in real library docs.

Key patterns for reading library documentation

Read @param and @returns carefully — both the success and failure paths
? after a parameter name means it is optional; defaults apply if omitted
Caveats sections contain the most important warnings — read them first
Examples show one common path; the signature shows all possible inputs

0 / 5 completed

1 / 5

Read the following function signature from a library's documentation:

/**
 * Retries an async function up to `maxAttempts` times.
 *
 * @param fn        - The async function to retry. Receives the attempt number (1-based).
 * @param options   - Configuration object.
 * @param options.maxAttempts  - Maximum number of attempts. Default: 3.
 * @param options.delayMs      - Base delay between attempts in milliseconds. Default: 500.
 * @param options.backoff      - Multiply delay by this factor each attempt. Default: 2.
 * @returns Promise that resolves with the return value of `fn` on success,
 *          or rejects with the last error after all attempts are exhausted.
 *
 * @example
 * const data = await retry(
 *   async (attempt) => fetchUser(userId),
 *   { maxAttempts: 5, delayMs: 200, backoff: 1.5 }
 * );
 */
function retry<T>(fn: (attempt: number) => Promise<T>, options?: RetryOptions): Promise<T>

If maxAttempts is 5 and all 5 attempts fail, what does the function return?

2 / 5

The documentation includes this Caveats section:

## Caveats

- `fn` must be idempotent. Do not use `retry()` with functions that
  have unrecoverable side effects (e.g. charging a payment card,
  sending an email) unless your function handles deduplication internally.
- The delay before the first retry is `delayMs`. The delay before
  attempt N is `delayMs * backoff^(N-2)` for N >= 2.
- This function does NOT catch synchronous exceptions thrown by `fn`.
  Wrap your function body in a try/catch if it can throw synchronously.

A developer wants to use retry() to retry a failed API call that sends a password-reset email. According to the docs, this is risky because:

3 / 5

In the function signature: function retry<T>(fn: (attempt: number) => Promise<T>, options?: RetryOptions): Promise<T>

The trailing ? on options? means:

4 / 5

The example shows: async (attempt) => fetchUser(userId) — the attempt parameter is received but not used. Why might a real-world caller use the attempt number?

5 / 5

The Caveats section states: "This function does NOT catch synchronous exceptions thrown by fn."

A developer writes the code below. What will happen if JSON.parse(response.text) throws a SyntaxError?

const result = await retry(async () => {
  const response = await fetch(url);
  return JSON.parse(response.text); // <-- can throw SyntaxError
});