微软发起TSDoc项目试图规范文档格式

当年,Java的兴起有一个很重要的原因,就是它的文档非常好用(我知道有杠精要说外观不好看,但是对开发者来说真的很好用):

0_1531202808264_1.png

package、class、properties、methods,一目了然,查阅起来非常方便快捷。

这背后离不开JavaDoc这款工具的功劳。

在JavaScript领域,一直就缺乏很好用的文档工具,要么是生成的文档格式丑陋,要么就是限制太大,根本不可用。

这里面就包括你们念念叨叨的JSDoc,但是真的很不好意思,JSDoc生成出来的文档很像一坨shit,就比如这样的鬼畜格式,实在让人没有信心往下看:

0_1531203164819_2.png

当然,如果这样一说的话,Angular的文档就只能说是两坨shit了,你会看到这种东西:

0_1531203575714_3.png

Are you f**king kidding me? 这花花绿绿的一屏幕让开发者怎么查找?另外这种分类结构,让人怎么才能理解甚至记住?

如果你有兴趣切换一下版本号的话,里面的内容就更加混乱得不忍直视了:

0_1531203835924_4.png

这里有一个例外,那就是ExtJS(起源于2007年,现在叫Sencha)的文档,非常的优美和实用:

0_1531204081393_5.png

来来来,再仔细看看这格式:

0_1531204100531_6.png

再仔细看看这内容:

0_1531204118930_7.png

这才是开发者真正想要的文档好不好?

ExtJS官方自己开发了一款基于Ruby的文档生成工具,名字叫做JSDuck。它详细定义了各种注释的形式,可以自动从JS代码里面抽取注释生成文档,有兴趣了解细节的自己点这里

0_1531204341344_8.png

话说回来,文档混乱这口锅也不能全部交给工具来背,这里面有很大一块的原因是JS本身的特性导致,因为它过于动态,很多东西没法自动抽出来形成结构化的文档,比如一些全局变量。

所以问题就来了,既然TypeScript是“类型化的JavaScript”,那么基于TS编写的代码应该可以生成很好看的结构化文档才对。然而到目前为止,事实并非如此,不信你看上面Angular的文档,乱成狗。

原因在哪里呢?当然是TS语言本身啦,因为它没有像JDK那样内置一款好用的文档生成工具。最近 TypeScript 团队看起来突然意识到了文档的重要性,于是就发起了TSDoc这个项目了,看这里:https://github.com/Microsoft/tsdoc

特别注意:TSDoc这个项目刚刚起来,一个release都没有,所以目前还没法使用,希望TS团队加油,大干60天,发布1.0 !


本文由 @业余小编 原创,转发请保留签名,谢谢。
“Angular开发者”公众号,微信搜索:ngfans

你个麻瓜不识货,angular的文档是现在最好的文档

@testsla 睁着眼睛说瞎话

angular api文档如果翻译了就是最好的,任何文档只要翻译都是最好的.
换句话说,还有的连文档都没有纯靠源码猜

登录后回复

与 Angular开发者 的连接断开,我们正在尝试重连,请耐心等待