jsdoc-typescript-docs

JSDoc TypeScript 文档

为 TypeScript 代码库创建全面的内联文档。

核心工作流

1. 编写函数文档：参数、返回值、示例
2. 编写类型文档：接口、类型、枚举
3. 添加描述：用途和用法
4. 加入示例：代码示例
5. 生成文档：TypeDoc 输出
6. 集成 CI：自动生成文档

函数文档

基本函数

/**
 * 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);
}

异步函数

/**
 * 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();
}

泛型函数

/**
 * 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);
}

重载函数

/**
 * 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();
}

接口文档

/**
 * 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 preferred language code (e.g., 'en', 'es') */
  language: string;

  /** User's timezone (e.g., 'America/New_York') */
  timezone: string;

  /** User notification preferences */
  notifications: NotificationSettings;
}

类型文档

/**
 * HTTP methods supported by the API.
 */
export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';

/**
 * Configuration options for API requests.
 *
 * @typeParam TBody - The type of the request body
 */
export type RequestConfig<TBody = unknown> = {
  /** HTTP method to use */
  method: HttpMethod;

  /** Request headers */
  headers?: Record<string, string>;

  /** Request body (for POST, PUT, PATCH) */
  body?: TBody;

  /** Request timeout in milliseconds */
  timeout?: number;

  /** Number of retry attempts on failure */
  retries?: number;
};

/**
 * Result type for operations that can fail.
 *
 * @typeParam T - The type of the success value
 * @typeParam E - The type of the error value
 *
 * @example
 * ```typescript
 * function divide(a: number, b: number): Result<number, string> {
 *   if (b === 0) {
 *     return { success: false, error: 'Division by zero' };
 *   }
 *   return { success: true, data: a / b };
 * }
 * ```
 */
export type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E };

类文档

/**
 * A client for interacting with the API.
 *
 * @remarks
 * This client handles authentication, retries, and error handling
 * automatically. Use the {@link ApiClient.create} factory method
 * to create an instance.
 *
 * @example
 * ```typescript
 * const client = ApiClient.create({
 *   baseUrl: 'https://api.example.com',
 *   apiKey: process.env.API_KEY,
 * });
 *
 * const users = await client.get<User[]>('/users');
 * ```
 */
export class ApiClient {
  /**
   * The base URL for all API requests.
   * @readonly
   */
  readonly baseUrl: string;

  /**
   * Creates a new ApiClient instance.
   *
   * @param config - The client configuration
   * @returns A new ApiClient instance
   *
   * @example
   * ```typescript
   * const client = ApiClient.create({ baseUrl: 'https://api.example.com' });
   * ```
   */
  static create(config: ApiClientConfig): ApiClient {
    return new ApiClient(config);
  }

  /**
   * @internal
   */
  private constructor(private config: ApiClientConfig) {
    this.baseUrl = config.baseUrl;
  }

  /**
   * Performs a GET request.
   *
   * @typeParam T - The expected response type
   * @param endpoint - The API endpoint (relative to baseUrl)
   * @param options - Optional request configuration
   * @returns A promise that resolves to the response data
   *
   * @throws {ApiError} When the request fails
   *
   * @example
   * ```typescript
   * interface User { id: string; name: string; }
   * const users = await client.get<User[]>('/users');
   * ```
   */
  async get<T>(endpoint: string, options?: RequestOptions): Promise<T> {
    return this.request<T>('GET', endpoint, options);
  }

  /**
   * Performs a POST request.
   *
   * @typeParam T - The expected response type
   * @typeParam TBody - The request body type
   * @param endpoint - The API endpoint
   * @param body - The request body
   * @param options - Optional request configuration
   * @returns A promise that resolves to the response data
   */
  async post<T, TBody = unknown>(
    endpoint: string,
    body: TBody,
    options?: RequestOptions
  ): Promise<T> {
    return this.request<T>('POST', endpoint, { ...options, body });
  }

  /**
   * @internal
   */
  private async request<T>(
    method: HttpMethod,
    endpoint: string,
    options?: RequestOptions
  ): Promise<T> {
    // Implementation
  }
}

枚举文档

/**
 * Status codes for order processing.
 *
 * @remarks
 * Orders progress through these statuses in sequence,
 * though they may skip directly to `Cancelled` from any state.
 */
export enum OrderStatus {
  /** Order has been created but not yet processed */
  Pending = 'pending',

  /** Payment has been received and order is being prepared */
  Processing = 'processing',

  /** Order has been shipped to the customer */
  Shipped = 'shipped',

  /** Order has been delivered to the customer */
  Delivered = 'delivered',

  /** Order has been cancelled */
  Cancelled = 'cancelled',

  /** Order has been returned by the customer */
  Returned = 'returned',
}

React 组件文档

/**
 * A customizable button component.
 *
 * @remarks
 * This button supports multiple variants, sizes, and states.
 * It is fully accessible and supports keyboard navigation.
 *
 * @example
 * ```tsx
 * // Basic usage
 * <Button onClick={handleClick}>Click me</Button>
 *
 * // With variant and size
 * <Button variant="secondary" size="lg">
 *   Large Secondary Button
 * </Button>
 *
 * // Loading state
 * <Button loading>Submitting...</Button>
 * ```
 */
export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  /**
   * The visual style variant.
   * @default 'primary'
   */
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';

  /**
   * The size of the button.
   * @default 'md'
   */
  size?: 'sm' | 'md' | 'lg';

  /**
   * Whether the button is in a loading state.
   * When true, the button is disabled and shows a spinner.
   * @default false
   */
  loading?: boolean;

  /**
   * Icon to display before the button text.
   */
  leftIcon?: React.ReactNode;

  /**
   * Icon to display after the button text.
   */
  rightIcon?: React.ReactNode;
}

/**
 * A customizable button component.
 *
 * @param props - The component props
 * @returns The rendered button element
 *
 * @see {@link ButtonProps} for available props
 */
export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant = 'primary', size = 'md', loading, children, ...props }, ref) => {
    // Implementation
  }
);

Button.displayName = 'Button';

TypeDoc 配置

// typedoc.json
{
  "entryPoints": ["./src/index.ts"],
  "out": "./docs",
  "name": "My Library",
  "readme": "./README.md",
  "plugin": [
    "typedoc-plugin-markdown",
    "typedoc-plugin-mdn-links"
  ],
  "excludePrivate": true,
  "excludeProtected": true,
  "excludeInternal": true,
  "includeVersion": true,
  "categorizeByGroup": true,
  "categoryOrder": ["Core", "Utilities", "Types", "*"],
  "navigationLinks": {
    "GitHub": "https://github.com/user/repo",
    "npm": "https://www.npmjs.com/package/my-package"
  },
  "validation": {
    "notExported": true,
    "invalidLink": true,
    "notDocumented": false
  }
}

// package.json
{
  "scripts": {
    "docs": "typedoc",
    "docs:watch": "typedoc --watch"
  },
  "devDependencies": {
    "typedoc": "^0.25.0",
    "typedoc-plugin-markdown": "^3.17.0",
    "typedoc-plugin-mdn-links": "^3.1.0"
  }
}

JSDoc 标签参考

/**
 * Summary description.
 *
 * @remarks
 * Additional details and implementation notes.
 *
 * @param name - Parameter description
 * @typeParam T - Type parameter description
 * @returns Return value description
 *
 * @throws {ErrorType} When error condition
 *
 * @example
 * ```typescript
 * // Example code
 * ```
 *
 * @see {@link RelatedItem} for related documentation
 * @see https://example.com External link
 *
 * @deprecated Use `newFunction` instead
 * @since 1.0.0
 * @version 2.0.0
 *
 * @alpha - Early preview
 * @beta - Feature complete but may change
 * @public - Stable API
 * @internal - Not for public use
 * @readonly - Cannot be modified
 * @virtual - Can be overridden
 * @override - Overrides parent
 * @sealed - Cannot be extended
 *
 * @defaultValue default value
 * @eventProperty - For event properties
 */

最佳实践

1. 编写公开 API 文档：所有导出项都需要文档
2. 使用示例：展示实际用法
3. 描述参数：清晰、简洁地描述
4. 记录错误：说明可能抛出的错误
5. 链接相关项目：使用 @see 标签
6. 保持更新：确保文档与代码同步
7. 生成 HTML：使用 TypeDoc 生成可浏览的文档
8. 在 CI 中验证：检查是否有缺失的文档

输出检查清单

每个已编写文档的代码库都应包含：

• 所有公开函数的文档
• 所有接口和类型的文档
• 所有参数的说明
• 返回值的文档
• 复杂函数的示例
• 抛出错误的文档
• TypeDoc 配置
• 生成的文档
• CI 流水线中的文档
• 含 API 概览的 README