TypeDoc 基本使用 #

/**
 * 这是一个文档注释
 * 可以跨越多行
 * 
 * 第一段是简短描述
 * 后续段落是详细描述
 */

// 普通注释不会被 TypeDoc 提取
// 这只是代码注释

/* 
 * 这种注释也不会被提取
 */

┌─────────────────────────────────────────────────────────────┐
│                    文档注释结构                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  /**                                                        │
│   * 简短描述（第一段）                                       │
│   *                                                         │
│   * 详细描述（后续段落）                                     │
│   * 可以包含更多说明、注意事项等                             │
│   *                                                         │
│   * @param name - 参数标签                                   │
│   * @returns 返回值标签                                      │
│   * @example 示例标签                                        │
│   */                                                        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

/**
 * 计算两个数的和
 * @param a - 第一个加数
 * @param b - 第二个加数
 * @returns 两数之和
 */
function add(a: number, b: number): number {
  return a + b;
}

/**
 * 格式化日期为指定格式
 * 
 * 将日期对象转换为字符串，支持多种格式化选项。
 * 默认格式为 'YYYY-MM-DD'。
 * 
 * @param date - 要格式化的日期对象
 * @param format - 格式化模式，默认为 'YYYY-MM-DD'
 * @returns 格式化后的日期字符串
 * 
 * @example
 * ```typescript
 * formatDate(new Date()); // '2024-01-15'
 * formatDate(new Date(), 'YYYY/MM/DD'); // '2024/01/15'
 * formatDate(new Date(), 'MM-DD-YYYY'); // '01-15-2024'
 * ```
 */
function formatDate(
  date: Date,
  format: string = 'YYYY-MM-DD'
): string {
  // 实现...
}

/**
 * 创建用户对象
 * 
 * @param id - 用户唯一标识
 * @param name - 用户名称
 * @param options - 可选配置项
 * @param options.email - 邮箱地址
 * @param options.age - 用户年龄
 * @param options.role - 用户角色
 * @returns 完整的用户对象
 * 
 * @example
 * ```typescript
 * const user = createUser(1, 'John', {
 *   email: 'john@example.com',
 *   role: 'admin'
 * });
 * ```
 */
function createUser(
  id: number,
  name: string,
  options?: {
    email?: string;
    age?: number;
    role?: 'user' | 'admin';
  }
): User {
  return {
    id,
    name,
    ...options
  };
}

/**
 * 获取对象中指定键的值
 * 
 * @typeParam T - 对象类型
 * @typeParam K - 键类型，必须是 T 的键
 * @param obj - 源对象
 * @param key - 要获取的键
 * @returns 键对应的值
 * 
 * @example
 * ```typescript
 * const user = { name: 'John', age: 30 };
 * const name = getProperty(user, 'name'); // 'John'
 * ```
 */
function getProperty<T, K extends keyof T>(
  obj: T,
  key: K
): T[K] {
  return obj[key];
}

/**
 * 异步获取用户数据
 * 
 * 从服务器获取指定用户的信息。
 * 如果用户不存在，抛出 NotFoundError。
 * 
 * @param userId - 用户ID
 * @returns 用户数据对象
 * @throws {NotFoundError} 用户不存在时抛出
 * @throws {NetworkError} 网络错误时抛出
 * 
 * @example
 * ```typescript
 * try {
 *   const user = await fetchUser(123);
 *   console.log(user.name);
 * } catch (error) {
 *   console.error('获取用户失败', error);
 * }
 * ```
 */
async function fetchUser(userId: number): Promise<User> {
  const response = await fetch(`/api/users/${userId}`);
  if (!response.ok) {
    throw new NotFoundError(`User ${userId} not found`);
  }
  return response.json();
}

/**
 * 表示一个点在二维坐标系中的位置
 */
class Point {
  /**
   * X 坐标
   */
  x: number;

  /**
   * Y 坐标
   */
  y: number;

  /**
   * 创建一个新的点
   * @param x - X 坐标，默认为 0
   * @param y - Y 坐标，默认为 0
   */
  constructor(x: number = 0, y: number = 0) {
    this.x = x;
    this.y = y;
  }

  /**
   * 计算到原点的距离
   * @returns 到原点的距离
   */
  distanceFromOrigin(): number {
    return Math.sqrt(this.x ** 2 + this.y ** 2);
  }
}

/**
 * 用户管理服务
 * 
 * 提供用户的增删改查操作，支持本地存储和远程同步。
 * 
 * @example
 * ```typescript
 * const service = new UserService();
 * 
 * // 添加用户
 * const user = service.add({ name: 'John' });
 * 
 * // 获取用户
 * const found = service.get(user.id);
 * 
 * // 删除用户
 * service.remove(user.id);
 * ```
 */
class UserService {
  /**
   * 用户列表
   * @internal 内部使用
   */
  private users: Map<number, User> = new Map();

  /**
   * 下一个用户ID
   */
  private nextId: number = 1;

  /**
   * 创建用户服务实例
   * @param options - 配置选项
   */
  constructor(
    private options: UserServiceOptions = {}
  ) {}

  /**
   * 添加新用户
   * 
   * @param data - 用户数据
   * @returns 创建的用户对象
   * 
   * @example
   * ```typescript
   * const user = service.add({
   *   name: 'John',
   *   email: 'john@example.com'
   * });
   * ```
   */
  add(data: Omit<User, 'id'>): User {
    const user: User = {
      id: this.nextId++,
      ...data
    };
    this.users.set(user.id, user);
    return user;
  }

  /**
   * 根据ID获取用户
   * 
   * @param id - 用户ID
   * @returns 用户对象，不存在则返回 undefined
   */
  get(id: number): User | undefined {
    return this.users.get(id);
  }

  /**
   * 获取所有用户
   * 
   * @returns 用户列表
   */
  getAll(): User[] {
    return Array.from(this.users.values());
  }

  /**
   * 更新用户信息
   * 
   * @param id - 用户ID
   * @param data - 要更新的数据
   * @returns 更新后的用户对象
   * @throws {Error} 用户不存在时抛出
   */
  update(id: number, data: Partial<Omit<User, 'id'>>): User {
    const user = this.users.get(id);
    if (!user) {
      throw new Error(`User ${id} not found`);
    }
    Object.assign(user, data);
    return user;
  }

  /**
   * 删除用户
   * 
   * @param id - 用户ID
   * @returns 是否删除成功
   */
  remove(id: number): boolean {
    return this.users.delete(id);
  }
}

/**
 * 数据存储基类
 * 
 * 定义了数据存储的通用接口，子类需要实现具体的存储逻辑。
 * 
 * @typeParam T - 存储的数据类型
 */
abstract class Storage<T> {
  /**
   * 存储名称
   */
  abstract readonly name: string;

  /**
   * 保存数据
   * @param data - 要保存的数据
   */
  abstract save(data: T): Promise<void>;

  /**
   * 加载数据
   * @returns 加载的数据
   */
  abstract load(): Promise<T>;

  /**
   * 清除数据
   */
  abstract clear(): Promise<void>;
}

/**
 * 本地存储实现
 * 
 * @typeParam T - 存储的数据类型
 */
class LocalStorage<T> extends Storage<T> {
  readonly name: string;

  constructor(name: string) {
    super();
    this.name = name;
  }

  async save(data: T): Promise<void> {
    localStorage.setItem(this.name, JSON.stringify(data));
  }

  async load(): Promise<T> {
    const data = localStorage.getItem(this.name);
    return data ? JSON.parse(data) : null;
  }

  async clear(): Promise<void> {
    localStorage.removeItem(this.name);
  }
}

/**
 * 用户信息接口
 */
interface User {
  /** 用户唯一标识 */
  id: number;
  
  /** 用户名 */
  name: string;
  
  /** 邮箱地址 */
  email: string;
  
  /** 用户年龄 */
  age?: number;
}

/**
 * API 响应结构
 * 
 * @typeParam T - 响应数据类型
 */
interface ApiResponse<T> {
  /** 响应状态码 */
  code: number;
  
  /** 响应消息 */
  message: string;
  
  /** 响应数据 */
  data: T;
  
  /** 时间戳 */
  timestamp: number;
}

/**
 * 分页响应结构
 * 
 * @typeParam T - 列表项类型
 */
interface PaginatedResponse<T> extends ApiResponse<T[]> {
  /** 分页信息 */
  pagination: {
    /** 当前页码 */
    page: number;
    /** 每页数量 */
    pageSize: number;
    /** 总数量 */
    total: number;
    /** 总页数 */
    totalPages: number;
  };
}

/**
 * 事件处理函数类型
 */
interface EventHandler<T = void> {
  /**
   * 处理事件
   * @param event - 事件对象
   */
  (event: T): void;
}

/**
 * 比较函数类型
 * 
 * @typeParam T - 比较元素类型
 */
interface CompareFunction<T> {
  /**
   * 比较两个元素
   * @param a - 第一个元素
   * @param b - 第二个元素
   * @returns 负数表示 a < b，正数表示 a > b，0 表示相等
   */
  (a: T, b: T): number;
}

/**
 * 用户ID类型
 */
type UserId = number;

/**
 * 用户角色类型
 */
type UserRole = 'user' | 'admin' | 'guest';

/**
 * 可能是字符串或数字
 */
type StringOrNumber = string | number;

/**
 * 深度部分类型
 * 
 * 递归地将所有属性变为可选
 * 
 * @typeParam T - 原始类型
 */
type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object
    ? DeepPartial<T[P]>
    : T[P];
};

/**
 * 必选键类型
 * 
 * 从 T 中选取必须包含的键 K
 * 
 * @typeParam T - 对象类型
 * @typeParam K - 必选键
 */
type RequiredKeys<T, K extends keyof T> = T & Required<Pick<T, K>>;

/**
 * 函数返回类型提取
 * 
 * @typeParam T - 函数类型
 */
type AsyncReturnType<T extends (...args: any) => Promise<any>> =
  T extends (...args: any) => Promise<infer R> ? R : never;

/**
 * 用户状态枚举
 */
enum UserStatus {
  /** 活跃状态 */
  Active = 'active',
  
  /** 未激活状态 */
  Inactive = 'inactive',
  
  /** 已禁用状态 */
  Disabled = 'disabled',
  
  /** 已删除状态 */
  Deleted = 'deleted'
}

/**
 * HTTP 状态码
 */
enum HttpStatus {
  /** 成功 */
  OK = 200,
  
  /** 已创建 */
  Created = 201,
  
  /** 错误请求 */
  BadRequest = 400,
  
  /** 未授权 */
  Unauthorized = 401,
  
  /** 禁止访问 */
  Forbidden = 403,
  
  /** 未找到 */
  NotFound = 404,
  
  /** 服务器错误 */
  InternalServerError = 500
}

/**
 * @module UserService
 * 
 * 用户服务模块，提供用户管理相关的功能。
 * 
 * @example
 * ```typescript
 * import { UserService, User } from './user-service';
 * 
 * const service = new UserService();
 * const user = service.add({ name: 'John' });
 * ```
 */

/**
 * @packageDocumentation
 * 
 * 整个包的文档说明。
 * 这将作为包的主页面内容。
 */

/**
 * 工具函数模块
 */

/**
 * 深拷贝对象
 * 
 * @param obj - 要拷贝的对象
 * @returns 深拷贝后的新对象
 */
export function deepClone<T>(obj: T): T {
  return JSON.parse(JSON.stringify(obj));
}

/**
 * 防抖函数
 * 
 * @param fn - 要防抖的函数
 * @param delay - 延迟时间（毫秒）
 * @returns 防抖后的函数
 */
export function debounce<T extends (...args: any[]) => any>(
  fn: T,
  delay: number
): (...args: Parameters<T>) => void {
  let timer: ReturnType<typeof setTimeout>;
  return (...args) => {
    clearTimeout(timer);
    timer = setTimeout(() => fn(...args), delay);
  };
}

export { deepClone, debounce };

// ✅ 好的注释：简洁明了
/** 计算两数之和 */
function add(a: number, b: number): number {
  return a + b;
}

// ❌ 不好的注释：过于冗长
/**
 * 这个函数用于计算两个数字的和。
 * 它接受两个参数，都是数字类型，
 * 然后返回它们的和。
 * 这是一个非常简单的数学运算。
 */
function add(a: number, b: number): number {
  return a + b;
}

// ✅ 好的示例：展示实际用法
/**
 * 格式化货币金额
 * 
 * @param amount - 金额
 * @param currency - 货币代码，默认 'USD'
 * @returns 格式化后的货币字符串
 * 
 * @example
 * ```typescript
 * formatCurrency(1234.56); // '$1,234.56'
 * formatCurrency(1234.56, 'EUR'); // '€1,234.56'
 * formatCurrency(1234.56, 'JPY'); // '¥1,235'
 * ```
 */
function formatCurrency(
  amount: number,
  currency: string = 'USD'
): string {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency
  }).format(amount);
}

/**
 * 安全获取嵌套属性
 * 
 * @param obj - 源对象
 * @param path - 属性路径，用点号分隔
 * @param defaultValue - 默认值
 * @returns 属性值或默认值
 * 
 * @example
 * ```typescript
 * const obj = { a: { b: { c: 1 } } };
 * get(obj, 'a.b.c'); // 1
 * get(obj, 'a.b.d', 'default'); // 'default'
 * get(null, 'a.b.c'); // undefined
 * ```
 */
function get<T = any>(
  obj: any,
  path: string,
  defaultValue?: T
): T | undefined {
  if (!obj) return defaultValue;
  
  const keys = path.split('.');
  let result = obj;
  
  for (const key of keys) {
    if (result[key] === undefined) {
      return defaultValue;
    }
    result = result[key];
  }
  
  return result;
}

/**
 * 用户服务
 * 
 * 提供用户的增删改查操作。
 * 
 * @see {@link User} 用户类型定义
 * @see {@link UserServiceOptions} 服务配置选项
 * @see {@link https://example.com/api/users | API 文档}
 */
class UserService {
  // ...
}

/**
 * 旧版用户获取方法
 * 
 * @deprecated 请使用 {@link UserService.get} 替代
 * 该方法将在 v2.0.0 版本移除
 * 
 * @param id - 用户ID
 * @returns 用户对象
 */
function getUserLegacy(id: number): User | undefined {
  console.warn('getUserLegacy is deprecated, use UserService.get instead');
  return userService.get(id);
}