什么是 TSDoc？
TSDoc 是一个旨在标准化 TypeScript 代码中使用的文档注释的提案，以便不同的工具可以提取内容而不会被彼此的标记混淆。TSDoc 符号看起来非常熟悉
export class Statistics {
/**
* Returns the average of two numbers.
*
* @remarks
* This method is part of the {@link core-library#Statistics | Statistics subsystem}.
*
* @param x - The first input number
* @param y - The second input number
* @returns The arithmetic mean of `x` and `y`
*
* @beta
*/
public static getAverage(x: number, y: number): number {
return (x + y) / 2.0;
}
}
我们正在开发一个库包 @microsoft/tsdoc，它提供了一个解析器的开源参考实现。使用这个库可以很容易地确保您的工具 100% 兼容该标准。
👋 *试试看！ TSDoc Playground 提供了解析器的交互式演示！*
我们为什么需要 TSDoc？
一个源文件可能被多个工具分析。以下是一些需要解析文档注释的流行工具的示例
- TypeDoc：一个 API 参考生成器，它从代码注释中提取成员文档
- DocFX：一个集成的管道，它摄取多种不同编程语言的 API 参考内容，然后应用其自己的 Markdown 渲染器和自定义标签解析
- API Extractor：一个构建工具，它跟踪 TypeScript API 审查工作流程并生成用于第三方 SDK 的 .d.ts 汇总*.d.ts 汇总，用于第三方 SDK
- ESLint：lint 规则可能会查找诸如
@virtual或@override之类的标签，这些标签表示要验证的行为契约 - Visual Studio Code：一个编辑器，它支持 TypeScript 文档注释的语法高亮和交互式重构
- 您自己的脚本！ - 开发人员经常创建从代码注释中提取文档或捆绑指令的构建脚本
所有这些工具都识别一种松散地基于 JSDoc 的语法，但每个工具都有自己风格的语法扩展。这可能会导致令人沮丧的不兼容性。
考虑一个假设的输入
/**
* @returns true if the specified tag is surrounded with `{`
* and `}` characters.
*
* @example
* Prints "true" for `{@link}` but "false" for `@internal`:
* ```ts
* console.log(isInlineTag('{@link}'));
* console.log(isInlineTag('@internal'));
* ```
* @see {@link http://example.com/@internal | the @internal tag}
*/
declare function isInlineTag(tagName: string): boolean;
这个 isInlineTag() 函数是否被标记为 @internal？嗯，API Extractor 会说“否”，因为它识别许多 CommonMark 结构。但是 TypeScript 编译器会说“是”——即使对于 @see 超文本和 URL——因为它的解析器将所有内容都视为字面文本。
@see 块是 @example 的一部分吗？同样，不同的工具会根据它们如何处理该标签而表现不同。
在许多情况下，草率的解析在很大程度上是有效的。偶尔的故障没什么大不了的。但是，当这些指令决定专业的网站内容或构建输出时，不正确的解析可能会成为一个严重的问题。
三个要求
TSDoc 旨在标准化文档注释语法，同时仔细平衡几个相互竞争的设计要求
- 可扩展性： 工具必须能够定义自己的自定义标签，以自然的方式表示特定于领域的元数据。
- 互操作性： 自定义标签不得阻止其他工具正确分析注释。换句话说，自定义标签必须使用已建立的语法模式，这些模式可以在解析期间被安全地识别和丢弃。
- 熟悉的语法： 尽可能地，TSDoc 应该保留 JSDoc/Markdown 的熟悉风格。这也最大程度地提高了旧注释将作为 TSDoc 正确解析的可能性。
为什么 JSDoc 不能成为标准？ JSDoc 语法没有严格指定，而是从特定实现的行为中推断出来的。大多数标准 JSDoc 标签都专注于为纯 JavaScript 提供类型注释，这对于像 TypeScript 这样的强类型语言来说不是主要关注点。
谁参与其中？
实现
- Pete Gonzalez 创建了最初的概念和解析器 API
- Ron Buckton 重新设计了声明引用语法，并且一直在从事 markdown 解析器的重写工作
- Ian Clanton-Thuon 贡献了 TSDoc Playground
- Brian Folts 为 ESLint 贡献了 eslint-plugin-tsdoc 包
- 许多其他贡献者实现了功能和错误修复！
（您的名字应该出现在这里吗？建议更新此页面。）
贡献设计输入
- Microsoft 的 TypeScript 编译器组
- API Extractor 社区
- DocFX 维护者
- TypeDoc 社区
- SimplrJS 开发人员，他们维护了 ts-docs-gen 工具
- Tom Dale，他正在为 Ember.js、Glimmer.js 和其他项目开发文档引擎
- Rob Eisenberg，他正在为 Aurelia 开发文档引擎。
下一步
👉 了解更多 -- 关于目标和方法
👉 我该如何使用 TSDoc？ -- 了解使用 TSDoc 进行开发的工具和资源