jsdoc-conventions

JSDoc Conventions for TypeScript

Enforcement Levels

Three levels control documentation scope. Each level includes all requirements from the previous one.

Minimal

Document exported functions, classes, interfaces, and type aliases with a brief summary line.

/** Parses a raw CSV string into structured row objects. */
export const parseCsv = (raw: string): CsvRow[] => { ... };

/** Represents a single row of parsed CSV data. */
export interface CsvRow { ... }

Standard

Everything in Minimal, plus:

• @param and @returns tags on exported functions
• Public class methods documented
• Complex type parameters described

/**
 * Fetches a user by ID from the database.
 *
 * @param userId - The unique identifier of the user
 * @returns The user object, or undefined if not found
 */
export const getUser = async (userId: string): Promise<User | undefined> => { ... };

Strict

Everything in Standard, plus:

• Module-level constants documented
• Private and internal helper functions documented
• @example blocks on non-trivial functions
• @throws, @see, and {@link} where applicable

/** Maximum number of retry attempts for failed API calls. */
const MAX_RETRIES = 3;

/**
 * Retries an async operation with exponential backoff.
 *
 * @param fn - The async function to retry
 * @param maxAttempts - Maximum retry attempts (defaults to {@link MAX_RETRIES})
 * @returns The result of the first successful invocation
 * @throws {RetryExhaustedError} When all attempts fail
 *
 * @example
 * ```ts
 * const data = await retry(() => fetchApi("/users"), 5);
 * ```
 *
 * @see {@link MAX_RETRIES} for the default retry limit
 */
const retry = async <TResult>(
  fn: () => Promise<TResult>,
  maxAttempts: number = MAX_RETRIES,
): Promise<TResult> => { ... };

Core Rules (All Levels)

Format

• Always use /** */ block comments, never // for documentation
• First line is a concise summary ending with a period
• Separate summary from tags with a blank line