@Rays
2018-04-20T11:04:35.000000Z
字数 1265
阅读 6151
语言开发
摘要: TSDoc项目提出了一种新的TypeScript源代码文档生成格式。已有的TypeScript API文档解析器支持基于JSDoc的语法,但是各种JSDoc扩展在实现上存在不一致。
作者: Dylan Schiemann
正文:
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格式列出了如下目标:
此外,TSDoc引用解析器目标是提供:
TypeScript开发人员正致力于那些与TypeScript已提供类型信息冗余的JSDoc类型注释,有望实现它们同样也可用于TSDoc。
鉴于TSDoc尚处于早期阶段,项目希望对此感兴趣的组织能参与进来,共同将TSDoc打造成为一种适用于所有TypeScript源代码文档生成的方法。欢迎通过TSDoc的GitHub项目做出贡献。
查看英文原文: TSDoc: A TypeScript Source Code Documentation Format