BT

如何利用碎片时间提升技术认知与能力? 点击获取答案

TSDoc:TypeScript源代码文档生成格式

| 作者 Dylan Schiemann 关注 7 他的粉丝 ,译者 盖磊 关注 2 他的粉丝 发布于 2018年5月2日. 估计阅读时间: 3 分钟 | QCon上海2018 关注大数据平台技术选型、搭建、系统迁移和优化的经验。

看新闻很累?看技术新闻更累?试试下载InfoQ手机客户端,每天上下班路上听新闻,有趣还有料!

TSDoc项目提出了一种新的TypeScript源代码文档生成格式。已有的TypeScript API文档解析器支持基于JSDoc的语法,但是各种JSDoc扩展在实现上存在不一致。

据TSDoc项目介绍,尽管JSDoc是JavaScript源代码文档生成的事实标准,但是它并未满足TypeScript文档生成的需求:

不幸的是,JSDoc语法的定义尚未严格规范,而是根据特定实现的行为推断而来。大部分标准JSDoc标签侧重于为JavaScript文本提供类型注释,而类型注释并非TypeScript等强类型语言的关注点。

TSDoc语法目前处于前期规划阶段,尚未给出官方发布。在规划阶段,TypeScript团队和API ExtractorTypeDocDocFXts-docs-genEmber.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

评价本文

专业度
风格

您好,朋友!

您需要 注册一个InfoQ账号 或者 才能进行评论。在您完成注册后还需要进行一些设置。

获得来自InfoQ的更多体验。

告诉我们您的想法

允许的HTML标签: a,b,br,blockquote,i,li,pre,u,ul,p

当有人回复此评论时请E-mail通知我
社区评论

允许的HTML标签: a,b,br,blockquote,i,li,pre,u,ul,p

当有人回复此评论时请E-mail通知我

允许的HTML标签: a,b,br,blockquote,i,li,pre,u,ul,p

当有人回复此评论时请E-mail通知我

讨论

登陆InfoQ,与你最关心的话题互动。


找回密码....

Follow

关注你最喜爱的话题和作者

快速浏览网站内你所感兴趣话题的精选内容。

Like

内容自由定制

选择想要阅读的主题和喜爱的作者定制自己的新闻源。

Notifications

获取更新

设置通知机制以获取内容更新对您而言是否重要

BT