低代码到底是不是行业毒瘤?一线大厂怎么做的?戳此了解>>> 了解详情
写点什么

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

2018 年 5 月 01 日

看新闻很累?看技术新闻更累?试试下载 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

2018 年 5 月 01 日 19:0012383
用户头像

发布了 376 篇内容, 共 94.6 次阅读, 收获喜欢 218 次。

关注

评论

发布
暂无评论
发现更多内容

「免费开源」基于Vue和Quasar的前端SPA项目crudapi后台管理系统实战之动态表关系管理(六)

crudapi

Vue crud crudapi quasar 表关系

ffmpeg完美实现解封装操作!

txp

音视频

【音视频】手把手带你实现超实用实时音视频工具

轻口味

android 音视频 WebRTC 移动端 OpenGL ES

区块链国富论——财富不是物,而是全球信用共识

CECBC区块链专委会

黄金交易

Java检查异常、非检查异常、运行时异常、非运行时异常的区别

Sakura

四月日更

2021 年带你漫游语音识别技术

清秋

人工智能 语音识别 智能音箱 签约计划 4月日更

从零开始带你打开批处理大门

xiezhr

doc 批处理 cmd

移动端混合开发选型方案分析

花花

移动端 移动开发· 签约计划

机器学习水水笔记之——世界是积木吗?

Nydia

签约计划

一篇文章带你彻底了解MySQL各种约束

若尘

MySQL 数据库 约束 四月日更

100万级车辆数据监控的hadoop大数据架构探索与实践

黑马腾云

大数据 flink hadoop 分布式 车联网

这些相见恨晚的命令行工具,你用过几个?

王坤祥

bash Linux Tool

线程池的引入和实践案例分享

小诚信驿站

线程池 线程池工作原理

自己挖的坑,自己填|靠谱点评

无量靠谱

美团面试题:String s = new String("111") 会创建几个对象?

Java小咖秀

Java string 面试题 java面试 java对象

广告投放预算低?千人成本低才是真的省!

󠀛Ferry

四月日更

和面试官简单聊聊 Elasticsearch

escray

elasticsearch elastic 4月日更 技术编辑能力考核

开源| DewCloud——通用物联网平台

云原生

物联网平台 物联网 开源项目 工业互联网 DewCloud

用户管理

在即

四月日更

如何从零搭建技术团队

石云升

团队建设 28天写作 职场经验 管理经验 4月日更

uni-app跨端开发H5、小程序、IOS、Android(八):理解uni-app生命周期

黑马腾云

小程序 uni-app ios android H5

聪明人的训练(十一)

Changing Lin

4月日更

自古彭城列九州 龙争虎斗几千秋|靠谱点评

无量靠谱

我一怒之下写了个抄袭举报工具!只因一觉醒来我的文章被多个平台抄袭!

1_bit

Python selenium 签约计划 文本分析 文章查重

干货版“测试小品”欢乐场景

清菡

自动化测试

模块1-作业

佛系少女

一文带你了解如何排查内存泄漏导致的页面卡顿现象

零一

chrome 前端 浏览器 内存泄露 问题处理

手把手教你基于Prometheus搭建监控告警系统

Java全栈封神

云原生 Prometheus 监控告警

从运营、产品和技术,多角度思考电商的营销体系建设

邴越

电商营销 优惠券

声网 Agora 初体验

若尘

声网 Agora

Prometheus官方文档Querying[三]function

卓丁

2021 ThoughtWorks 技术雷达峰会

2021 ThoughtWorks 技术雷达峰会

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