tsdoc-comments

使用 TSDoc 编写 API 注释

概述

TSDoc 是 TypeScript 代码文档的标准。它扩展了 JSDoc，加入了 TypeScript 特有的功能，例如泛型类型参数（@template）。良好的文档不仅会说明代码的作用，还会解释原因，并通过 IDE 工具提示和生成的文档帮助用户理解 API。

编写完善的文档可以减轻支持负担，并改善 API 使用者的开发体验。

适用场景

• 为公共 API 编写文档
• 为他人编写库代码
• 解释复杂的类型参数
• 根据代码生成文档
• 提供 IDE 工具提示

铁律

使用 TSDoc 为公共 API 编写文档。说明作用和原因，并提供示例。使用 @template 说明泛型类型参数。

检测

留意缺少文档的公共 API：

// RED FLAGS - Missing documentation
export function process(data: unknown): Result;  // What does it do?
export type Transform<T> = /* complex type */;   // What's T for?
export class ApiClient {                         // How do I use this?
  constructor(config: Config) {}
}

TSDoc 基本结构

/**
 * Short description of what this does.
 *
 * Longer explanation if needed. Explain why this exists,
 * when to use it, and any important caveats.
 *
 * @param paramName - Description of parameter
 * @returns Description of return value
 * @example
 * ```typescript
 * const result = myFunction('input');
 * console.log(result); // 'processed: input'
 * ```
 */
function myFunction(input: string): string {
  return `processed: ${input}`;
}

为函数编写文档

/**
 * Fetches user data from the API.
 *
 * Automatically handles authentication and retries failed requests
 * up to 3 times with exponential backoff.
 *
 * @param userId - The unique identifier for the user
 * @param options - Optional configuration for the request
 * @returns A promise that resolves to the user data
 * @throws {ApiError} When the user is not found or the request fails
 * @example
 * ```typescript
 * const user = await fetchUser('123');
 * console.log(user.name);
 * ```
 */
async function fetchUser(
  userId: string,
  options?: FetchOptions
): Promise<User> {
  // Implementation
}

为泛型类型编写文档

/**
 * Creates a partial version of a type where all properties are optional.
 *
 * @template T - The type to make partial
 * @example
 * ```typescript
 * interface User {
 *   name: string;
 *   age: number;
 * }
 *
 * type PartialUser = Partial<User>;
 * // { name?: string; age?: number; }
 * ```
 */
type MyPartial<T> = {
  [K in keyof T]?: T[K];
};

为类编写文档

/**
 * Client for interacting with the REST API.
 *
 * Handles authentication, request retries, and response parsing.
 * Create one instance per application and reuse it.
 *
 * @example
 * ```typescript
 * const client = new ApiClient({
 *   baseUrl: 'https://api.example.com',
 *   apiKey: process.env.API_KEY
 * });
 *
 * const users = await client.users.list();
 * ```
 */
export class ApiClient {
  /**
   * Creates a new API client instance.
   *
   * @param config - Configuration options for the client
   */
  constructor(config: ClientConfig) {}

  /**
   * Resources for managing users.
   */
  readonly users: UserResource;
}

常用 TSDoc 标签

/**
 * Description of the function.
 *
 * @param name - Parameter description
 * @returns Return value description
 * @throws {ErrorType} When/why this error is thrown
 * @example Code example showing usage
 * @deprecated Use newFunction instead. Will be removed in v2.0.
 * @see Related function or documentation
 * @internal For internal use only, not part of public API
 */

// For generic types:
/**
 * @template T - Description of type parameter
 * @template K - Description of second parameter
 */

// For class members:
/**
 * @readonly This property is read-only
 * @protected This member is protected
 */

抗压协议

编写代码文档时：

1. 为公共 API 编写文档：所有导出的内容都应有文档
2. 解释原因，而不只是作用：帮助用户做出正确的决策
3. 提供示例：展示真实的使用方式
4. 说明异常情况：可能出现什么问题，以及原因
5. 保持文档最新：代码变更时同步更新文档

危险信号

反模式	问题	解决方案
没有文档	用户只能猜测用法	添加 TSDoc 注释
“显而易见”的注释	// Adds 1 to x	解释原因，而不只是作用
文档过时	误导用户	随代码变更更新文档
缺少 @template	泛型含义不明	说明类型参数

常见的自我安慰

“代码会自我说明”

事实：代码展示的是发生了什么，而不是为什么。文档则解释意图和背景。

“我以后再写文档”

事实：你不会的。趁上下文还清晰时，编写代码的同时写好文档。

“这只是内部代码”

事实：未来的你和同事也是用户。任何不明显的内容都应写入文档。

快速参考

标签	用途
@param	函数参数
@returns	返回值说明
@template	泛型类型参数
@example	使用示例
@throws	抛出的异常
@deprecated	标记已弃用的 API
@see	相关文档

总结

使用 TSDoc 为公共 API 编写文档。说明函数的作用、存在的原因以及使用方法。完善的文档会显示在 IDE 工具提示中，并减轻支持负担。

参考资料

• Dan Vanderkam 著《Effective TypeScript》第 2 版
• 条目 68：使用 TSDoc 编写 API 注释