看新闻很累?看技术新闻更累?试试下载 InfoQ 手机客户端,每天上下班路上听新闻,有趣还有料!
TSDoc 项目提出了一种新的 TypeScript 源代码文档生成格式。已有的 TypeScript API 文档解析器支持基于 JSDoc 的语法,但是各种 JSDoc 扩展在实现上存在不一致。
据 TSDoc 项目介绍,尽管 JSDoc 是 JavaScript 源代码文档生成的事实标准,但是它并未满足 TypeScript 文档生成的需求:
不幸的是,JSDoc 语法的定义尚未严格规范,而是根据特定实现的行为推断而来。大部分标准 JSDoc 标签侧重于为 JavaScript 文本提供类型注释,而类型注释并非 TypeScript 等强类型语言的关注点。
TSDoc 语法目前处于前期规划阶段,尚未给出官方发布。在规划阶段, TypeScript 团队和 API Extractor 、 TypeDoc 、 DocFX 、 ts-docs-gen 和 Ember.js 等项目的开发人员正就此开展合作。TypeScript 的程序经理 Daniel Rosenwasser 向 InfoQ 介绍了推出 TSDoc 项目的动机:
TSDoc 源自于人们希望能有组织地改进 TypeScript 文档生成工具的初衷。我们看到大家对此颇具兴趣,并且已多个团队着手去解决这个问题,但每个人都是各自为政的。TSDoc 的目的是使大家在行为上保持一致。在我看来,这是文档生成工具开发人员间的一次很好的协作机会,可以解决大家普遍面对的问题。
项目规划以 npm 软件包@microsoft/tsdoc
的形式发布,其中提供 TSDoc 引用解析器的开源实现。
TSDoc 格式列出了如下目标:
- 扩展 JSDoc,同时设计一种用于 TypeScript 的语法;
- 支持在注释中使用 Markdown 语法;
- 提供一组通用的文档标签;
- 提供可扩展的标签添加机制;
- 互操作性。自定义标签不会破坏非定制标签的解析和 Markdown 歧义的处理;
- 软件包和依赖关系间的交叉引用;
- 开放的标准。
此外,TSDoc 引用解析器目标是提供:
- 严格模式和宽松模式。其中,宽松模式力图实现对基于 JSDoc 的现有语法的解析;
- 文档注释和抽象语法树之间的双向往返解析;
- 提供自包含的、不依赖于 TypeScript 编译器的 API,支持将注释的抽象语法树转化为一个简单基本的 JavaScript 对象树。
TypeScript 开发人员正致力于那些与 TypeScript 已提供类型信息冗余的 JSDoc 类型注释,有望实现它们同样也可用于 TSDoc。
鉴于 TSDoc 尚处于早期阶段,项目希望对此感兴趣的组织能参与进来,共同将 TSDoc 打造成为一种适用于所有 TypeScript 源代码文档生成的方法。欢迎通过 TSDoc 的 GitHub 项目做出贡献。
查看英文原文: TSDoc: A TypeScript Source Code Documentation Format
评论