微軟發起TSDoc項目試圖規範文檔格式

來自專欄大漠窮秋的專欄91 人贊了文章

當年，Java的興起有一個很重要的原因，就是它的文檔非常好用（我知道有杠精要說外觀不好看，但是對開發者來說真的很好用）：

package、class、properties、methods，一目了然，查閱起來非常方便快捷。

這背後離不開JavaDoc這款工具的功勞。

在JavaScript領域，一直就缺乏很好用的文檔工具，要麼是生成的文檔格式醜陋，要麼就是限制太大，根本不可用。

這裡面就包括你們念念叨叨的[JSDoc](Use JSDoc: Index)，但是真的很不好意思，JSDoc生成出來的文檔很像一坨shit，就比如這樣的鬼畜格式，實在讓人沒有信心往下看：

當然，如果這樣一說的話，Angular的文檔就只能說是兩坨shit了，你會看到這種東西：

Are you f**king kidding me? 這花花綠綠的一屏幕讓開發者怎麼查找？另外這種分類結構，讓人怎麼才能理解甚至記住？

如果你有興趣切換一下版本號的話，裡面的內容就更加混亂得不忍直視了：

這裡有一個例外，那就是ExtJS（起源於2007年，現在叫Sencha）的文檔，非常的優美和實用：

來來來，再仔細看看這格式：

再仔細看看這內容：

這才是開發者真正想要的文檔好不好？

ExtJS官方自己開發了一款基於Ruby的文檔生成工具，名字叫做JSDuck。它詳細定義了各種注釋的形式，可以自動從JS代碼裡面抽取注釋生成文檔，[有興趣了解細節的自己點這裡](senchalabs/jsduck)。

話說回來，文檔混亂這口鍋也不能全部交給工具來背，這裡面有很大一塊的原因是JS本身的特性導致，因為它過於動態，很多東西沒法自動抽出來形成結構化的文檔，比如一些全局變數。

所以問題就來了，既然TypeScript是「類型化的JavaScript」，那麼基於TS編寫的代碼應該可以生成很好看的結構化文檔才對。然而到目前為止，事實並非如此，不信你看上面Angular的文檔，亂成狗。

原因在哪裡呢？當然是TS語言本身啦，因為它沒有像JDK那樣內置一款好用的文檔生成工具。最近 TypeScript 團隊看起來突然意識到了文檔的重要性，於是就發起了TSDoc這個項目了，看這裡：Microsoft/tsdoc

特別注意：TSDoc這個項目剛剛起來，一個release都沒有，所以目前還沒法使用，希望TS團隊加油，大幹60天，發布1.0 ！

本文由 @業餘小編 原創，轉發請保留簽名，謝謝。

「Angular開發者」公眾號，微信搜索：ngfans