方法

TSDoc 规范旨在满足以下要求

• 为 TypeScript 设计：...同时尽可能与我们熟悉和喜爱的 JSDoc 注释保持一致。
• Markdown 集成：文档注释可以包含 CommonMark 注释，用于富文本元素，例如粗体、代码围栏、标题、表格等。（这被证明是最棘手的要求，因为 Markdown 语法非常不规则，并且非常依赖于上下文。）TSDoc 为期望自带 Markdown 渲染器的根深蒂固的管道（例如 GitHub Pages）做出特殊调整。
• 通用核心：通用标签（例如 @param 和 @returns）在所有工具中都将具有一致的行为。
• 可扩展：每个工具都可以使用自定义标签来补充核心标签，以用于专门的场景。
• 互操作性：TSDoc 标准保证不受支持的自定义标签不会干扰其他内容的解析。TSDoc 还消除了 Markdown 的歧义。（反引号是否允许在 {@link} 标签内？如果只有一个反引号会发生什么？等等。）
• 多包支持：许多团队发布一组协同工作的 NPM 包，并将其作为一组文档记录。交叉引用语法（例如 {@link} 或 {@inheritDoc}）需要一种可移植的方式来引用从其他包导入的 API 项。我们还定义了 package.json 元数据，使工具能够检测依赖项的*.d.ts 文档注释是否应解析为 TSDoc。
• 开放标准：TSDoc 是一个开源的、社区驱动的标准。我们鼓励您贡献自己的想法和拉取请求。

@microsoft/tsdoc 库包带来了一些额外的目标

• “严格”和“宽松”模式：许多项目没有时间和意愿更改其现有代码，因此他们需要“宽松”模式，以尽力按原样渲染其文档注释。其他项目需要“严格”模式，以确保各处语法一致，并捕获可能导致渲染错误的拼写错误。一些项目最终想要“严格”，但他们无法在一夜之间迁移所有内容；他们需要类似于 tslint 抑制的“过渡”模式。
• 用于往返的注释发射器：解析器读取文档注释作为输入，并生成抽象语法树 (AST) 作为输出。这应该是可逆的：给定一个 AST 输入（可能经过修改），该库可以重新生成相应的文档注释。
• 自包含：该实现将是小巧、快速且自包含的。它不会依赖于 TypeScript 编译器 API。文档注释将作为纯文本字符串接收，AST 将是一个简单的 JavaScript 树对象。这使得工具更容易接受 @microsoft/tsdoc 作为依赖项。