JSDoc TypeScript Documentation

Create comprehensive inline documentation for TypeScript codebases.

Core Workflow

1. Document functions: Parameters, returns, examples
2. Document types: Interfaces, types, enums
3. Add descriptions: Purpose and usage
4. Include examples: Code samples
5. Generate docs: TypeDoc output
6. Integrate CI: Automated doc generation

Function Documentation

Basic Function

/**
 * Calculates the total price including tax.
 *
 * @param price - The base price before tax
 * @param taxRate - The tax rate as a decimal (e.g., 0.08 for 8%)
 * @returns The total price including tax
 *
 * @example
 * ```typescript
 * const total = calculateTotal(100, 0.08);
 * console.log(total); // 108
 * ```
 */
export function calculateTotal(price: number, taxRate: number): number {
  return price * (1 + taxRate);
}

Async Function

/**
 * Fetches user data from the API.
 *
 * @param userId - The unique identifier of the user
 * @param options - Optional configuration for the request
 * @returns A promise that resolves to the user data
 *
 * @throws {NotFoundError} When the user doesn't exist
 * @throws {NetworkError} When the request fails
 *
 * @example
 * ```typescript
 * try {
 *   const user = await fetchUser('user-123');
 *   console.log(user.name);
 * } catch (error) {
 *   if (error instanceof NotFoundError) {
 *     console.log('User not found');
 *   }
 * }
 * ```
 */
export async function fetchUser(
  userId: string,
  options?: FetchOptions
): Promise<User> {
  const response = await fetch(`/api/users/${userId}`, options);

  if (response.status === 404) {
    throw new NotFoundError(`User ${userId} not found`);
  }

  if (!response.ok) {
    throw new NetworkError('Failed to fetch user');
  }

  return response.json();
}

Generic Function

/**
 * Filters an array based on a predicate function.
 *
 * @typeParam T - The type of elements in the array
 * @param array - The array to filter
 * @param predicate - A function that returns true for elements to keep
 * @returns A new array containing only elements that pass the predicate
 *
 * @example
 * ```typescript
 * const numbers = [1, 2, 3, 4, 5];
 * const evens = filterArray(numbers, n => n % 2 === 0);
 * // evens: [2, 4]
 * ```
 */
export function filterArray<T>(
  array: T[],
  predicate: (item: T, index: number) => boolean
): T[] {
  return array.filter(predicate);
}

Overloaded Function

/**
 * Formats a value for display.
 *
 * @param value - The value to format
 * @returns The formatted string
 */
export function format(value: number): string;
/**
 * Formats a value with a specific format string.
 *
 * @param value - The value to format
 * @param formatStr - The format string (e.g., 'currency', 'percent')
 * @returns The formatted string
 */
export function format(value: number, formatStr: string): string;
/**
 * @internal
 */
export function format(value: number, formatStr?: string): string {
  if (formatStr === 'currency') {
    return `$${value.toFixed(2)}`;
  }
  if (formatStr === 'percent') {
    return `${(value * 100).toFixed(1)}%`;
  }
  return value.toString();
}

Interface Documentation

/**
 * Represents a user in the system.
 *
 * @example
 * ```typescript
 * const user: User = {
 *   id: 'user-123',
 *   email: '[email protected]',
 *   name: 'John Doe',
 *   role: 'admin',
 *   createdAt: new Date(),
 * };
 * ```
 */
export interface User {
  /**
   * The unique identifier for the user.
   * @example 'user-123'
   */
  id: string;

  /**
   * The user's email address.
   * @example '[email protected]'
   */
  email: string;

  /**
   * The user's display name.
   * @example 'John Doe'
   */
  name: string;

  /**
   * The user's role in the system.
   * @default 'user'
   */
  role: 'admin' | 'user' | 'guest';

  /**
   * When the user account was created.
   */
  createdAt: Date;

  /**
   * When the user account was last updated.
   * @optional
   */
  updatedAt?: Date;

  /**
   * The user's profile settings.
   * @see {@link UserProfile}
   */
  profile?: UserProfile;
}

/**
 * User profile configuration.
 */
export interface UserProfile {
  /** URL to the user's avatar image */
  avatarUrl?: string;

  /** User's prefer