TypeScript 文档：如何编写自解释的代码

引言：为什么文档不是枯燥的义务，而是一种超能力

想象一下：半年后你回到自己的项目。打开一个包含授权逻辑的文件——映入眼帘的是满屏的 TypeScript 代码。类型是有的，接口也定义了，但这个函数是做什么的？为什么参数叫 opts，它有哪些字段？是不是很熟悉？

TypeScript 中的文档不仅仅是“为了交差而写的注释”。它是一种工具，能将你的代码变成一个清晰易懂的故事。好的文档能节省数小时的调试时间，加速新人的入职过程，让你的 API 更加友好。在本文中，我们将探讨 TypeScript 项目文档化的最佳实践：从基础的 JSDoc 注释到使用 TypeDoc 的高级文档生成。开始吧！

1. JSDoc 和 TSDoc：文档的基础

TypeScript 从 JavaScript 继承了流行的 JSDoc 格式，随后社区开发了 TSDoc——一种针对 TypeScript 的标准化语法。如果你在编写库或 API，TSDoc 是你的首选。它更严格，能更好地与编辑器和文档生成器集成。

TSDoc 基本标签

以下是每位开发者都应该了解的最低限度内容：

\n
• @param — 函数参数的描述
\n
• @returns — 函数的返回值
\n
• @throws — 可能抛出的异常
\n
• @example — 使用示例
\n
• @deprecated — 标记已弃用的代码
\n

/**\n * 根据促销代码计算商品折扣。\n * \n * @param price - 商品原价（必须大于 0）\n * @param discountPercent - 折扣百分比（0 到 100 之间）\n * @param promoCode - 可能增加折扣的促销代码\n * @returns 应用折扣后的最终价格\n * @throws {Error} 如果价格或百分比无效\n * \n * @example\n * // 示例：1000 元商品打 20% 折扣\n * const finalPrice = calculateDiscount(1000, 20, 'SUMMER');\n * console.log(finalPrice); // 800\n */\nfunction calculateDiscount(\n  price: number,\n  discountPercent: number,\n  promoCode?: string\n): number {\n  if (price <= 0 || discountPercent < 0 || discountPercent > 100) {\n    throw new Error('无效参数');\n  }\n  \n  let discount = discountPercent;\n  if (promoCode === 'SUMMER') {\n    discount += 10; // 额外折扣\n  }\n  \n  return price * (1 - discount / 100);\n}\n

提示：始终描述边界情况。如果参数可能为 undefined，请在描述中说明。TypeScript 类型固然好，但人类语言能提供上下文。

2. 文档化类型和接口

TypeScript 的主要特性之一是其强大的类型系统。但即使是最严格的类型也无法解释字段的用途。像文档化函数一样仔细地文档化接口。

/**\n * 连接到外部天气 API 的配置。\n */\ninterface WeatherApiConfig {\n  /** API 的基础 URL（例如 https://api.weather.com） */\n  baseUrl: string;\n  \n  /** 从提供商处获取的身份验证密钥 */\n  apiKey: string;\n  \n  /** \n   * 等待服务器响应的秒数。\n   * 默认为 5 秒。\n   */\n  timeout?: number;\n  \n  /**\n   * API 版本。如果未指定，则使用最新的稳定版本。\n   * @deprecated 请在 URL 中使用 `version` 字段\n   */\n  apiVersion?: string;\n}\n

请注意：对于 timeout，我们直接在注释中指定了默认值。这使开发者无需查看源代码或测试。

3. 文档生成：将注释转化为网站

编写注释只是第一步。你需要能够将它们转化为方便的文档。对于 TypeScript，最好的工具是 TypeDoc。它会解析你的 TSDoc 注释