摘要：本文比較了種較為主流的注釋文檔生成工具。應該說是非常適合開源項目多個作者共同維護的一個文檔工具。最后我選擇了作為文檔生成的工具。為了支持多種語言，它僅對注釋塊內部的內容進行解析。

最近隨著寫Node以及獨立的CommonJS模塊越來越多，我發現有一份好的文檔不僅可以幫助自己在應用這些接口的時候不至于迷糊，而且對于共同開發的情況下，能夠省去大量團隊的交流和Debug的時間。

本文比較了5種較為主流的Javascript注釋文檔生成工具。需要指出的一點是，Javascript是一個極為靈活的語言，文檔生成并不像Java那樣具有絕對統一的規范，還要根據使用場景確定哪個工具更加適合。

JSDoc 3

YUIDoc

Dox

Docco

JSDuck

生成文檔的易讀性

工具的可擴展性

注釋語法標準

注釋語義的豐富程度

對沒有興趣了解細節比較的你，可以快速瀏覽下面的總結來了解這些工具。

YUIDoc是YUI的附屬項目。YUI團隊希望這個文檔工具不僅僅可以支持Javascript，而是更多的腳本語言，因此它并不考慮實際的代碼實施細節，而只是對注釋部分進行了掃描。從好的一面來說，如果你同時使用了Ruby/PHP/Python等等，YUI或許是一個比較適合的工具。從反面來說，因為它沒有考慮實施細節，你需要額外的變量聲明、同時生成的文檔有可能會和實際的實施細節不吻合。

JSDoc 3的前身是JSDoc Toolkit。它會對代碼的具體實施進行掃描，因此你如果不按照符合JSDoc的注釋語法來進行注釋的話，可能生成的文檔一個字也沒有。雖然它的學習曲線很高，但是一旦掌握了之后，由于它提供了完整的模版開發，事件觸發等等接口，其靈活性也是不容小覷的。

Dox是一個非常輕量級和可以定制化的工具，它使用和JSDoc 3兼容的注釋語法標準，并將其轉化成JSON格式。因此在呈現方式上具有比JSDoc 3更強的可定制性，當然也意味著你初期的麻煩會比較多。

Docco是一種行間注釋的方式。比起API注釋，它更適合于注釋代碼的實施邏輯，以便于后期程序員能夠快速捕捉到原作者在此處的實施意圖。應該說是非常適合開源項目、多個作者共同維護的一個文檔工具。比如最經典的Backbone Annotated Source就是使用Docco進行注釋的。

JSDuck由Sencha開發，因此對于自家extJS具有非常強大的支持功能，包括令人咋舌的實時代碼修改。但即使你不是使用extJS進行開發，JSDuck仍然是一個非常強大的工具，一方面它的語法非常靈活，描述支持Markdown語法，上手難度遠遠低于JSDoc 3；另一方面它生成的文檔可讀性堪比YUIDoc，同時支持源碼的對照，學習起來也非常的容易。要說JSDuck有什么不好的地方，估計就是它把一切都Handle太完美了以致于沒有給你提供什么可以自己定制的余地。

最后我選擇了JSDuck作為文檔生成的工具。從目的上說，我需要生成的是提供給Q&A和其他團隊成員參考的API文檔，考慮到畢竟寫代碼才是我們的主要工作，注釋和文檔越簡單能夠表達意思越好用，而JSDuck恰好十分符合我的需求。但是你選擇使用哪種工具還需要根據使用場景來具體考慮，還請參考下面的細節比較

YUIDoc
YUIDoc提供了非常清晰的文檔格式。不僅對象內部的內容非常清晰，而且相互引用的link也工作的非常好。同時YUIDoc提供了全局搜索的功能，你可以容易根據關鍵詞找到對應的內容。

JSDuck
JSDuck生成的文檔絕對不輸給YUIDoc。構造方法參數、屬性、方法都非常清晰的列在文檔之中。它的link也非常的好用，能夠準確的定位到不同模塊中的內容。JSDuck同樣提供了全局搜索的方法，而且還在你敲下關鍵詞的同時給你相關的提示。除了這些以外，JSDuck還提供了對于依賴(dependency)、以及查看源碼(View source)的方法。

JSDoc 3
JSDoc生成的文檔使用了Bootstrap樣式。默認的樣式非常非常的糟糕，不過JSDoc 3在自己的介紹頁面里推薦了一個第三方開發的模版系統“Docstrap”。這個模版雖然比JSDoc 3的默認模版好上很多，但是與YUIDoc和JSDuck生成的內容相比就差強人意了。其中的link的錨點也會偶爾不能正常工作。此外，它并不支持全局對于變量的搜索，你可以在Docstrap Github的issue中找到他們相關的開發計劃。
除了Docstrap以外，它還有一些推薦的模版系統，例如Jaguar，你也可以在這個基礎上開發自己的模版。

YUIDoc
由于YUIDoc是Yahoo下屬YUI項目的一個部分，它并不像JSDoc 3提供了那么多可定制的功能。能夠修改的大概就只有Logo，基本的CSS樣式而已。

JSDuck
JSDuck和YUIDoc的情況非常相似，屬于Sencha下屬的項目。樣式上能夠修改的也只有Logo而已。不過JSDuck靈活的地方在于，你可以定制文檔頂部的Tag：你可以除了文檔以外進一步包含視頻、教程等等多種內容。

JSDoc 3
JSDoc 3屬于完全開源的項目，因此如果你等不及社區的更新，你完全可以自己對JSDoc進行深度的開發。JSDoc對外提供的開發接口有3個：

模版Template

事件Event
其中最有意思的我認為是事件功能。JSDoc幾乎對載入文件、分析注釋和生成文檔的每一步都提供了事件的hook：parseBegin, fileBegin, beforeParse, jsdocCommentFound……通過這些事件，你甚至可以進一步定義自己需要的comment tag和解析規則。

插件Plugins

更加詳細的內容則可以在JSDoc的使用說明上找到詳細的講解。

最早這一票是投給JSDoc的，但是經過實際的測試之后發現JSDoc的語法標準非常嚴格，稍微不符合它的解析規則JSDoc便不能夠正確的生成文檔，其中最讓我不能接受的事情是它對于立刻執行函數IIFE的支持實在是％……&＊&＊……％（里面定義的內容大多被認為是不暴露在全局中的，非常不方便）
下面的說明中我給出了注釋一個函數的詳細示例。

    function exampleName(config, extra){
        extra = !!extra;   //set the default value of extra to false
        this.callback = config.callback;

        return this;
    }

從這個簡單的例子上幾乎不太能看出來三者實現的差別，但是當你要注釋命名空間、AMD或者CommonJS模塊的時候，三者的差別就會凸顯出來了。此外要聲明的一點是，三者的語法幾乎是不能通用的。我曾經試著將用YUIDoc注釋的文件使用JSDoc解析，結果非常悲劇，反之亦然。

YUIDoc
YUIDoc為了支持多種語言，它僅對注釋塊內部的內容進行解析。這意味著你需要對于函數、類、命名空間等的名稱和更多的內容進行顯性的聲明。此外，就像前文提到的，它可能會造成文檔和代碼實現的不一致，甚至對于接口的使用造成不好的影響。
YUIDoc對于注釋內容要求嚴格的兩層結構：Primary Tag和Secondary Tag
詳細的YUIDoc支持的語法標簽可以參考這里

/**
* My method description.  Like other pieces of your comment blocks, 
* this can span multiple lines.
*
* @method exampleName  此處必須顯性聲明method名稱
* @param {Object} config A config object
* @param {Function} config.callback A callback function on the config object
* @param {Boolean} [extra=false] Do extra, optional work
* @example
*     new exampleName(function(){console.log("Hello World")})
* @return {Object} Returns the constructed target object
*/

JSDuck
JSDuck在這點上恰好處在YUIDoc和JSDoc 3之間。它既對代碼的實現進行了最基本的解析，從中獲取對應的名稱、變量，有效的減少了Tag的使用。同時又不像JSDoc 3那樣嚴格，我嘗試了CommonJS、AMD和IIFE都能夠非常自然的生成對應的文檔。
詳細的JSDuck支持的語法標簽可以參考這里

/**
* My method description.  Like other pieces of your comment blocks, 
* this can span multiple lines.
*
*     new exampleName(function(){console.log("Hello World")})  JSDuck支持Markdown格式，插入代碼示例非常簡單
*
* @param {Object} config A config object
* @param {Function} config.callback A callback function on the config object
* @param {Boolean} [extra=false] Do extra, optional work
*     
* @return {Object} The constructed target object
* @return {Function} return.callback the callback function of the object  JSDuck可以支持返回對象的詳細結構注釋
*/

JSDoc 3
JSDoc 3很大程度上參考了Javadoc的實現。它有非常詳細的語法規則，并且你只有當和代碼實現完全一致的時候，它才能正確的生成文檔。但是對于Javascript這樣一門靈活的語言而言，這似乎并不是最適合的方式。雖然代碼有推薦的最佳實踐，但是為了讓文檔生成工具能夠正確識別而要對原本的代碼進行修改就有點僭越本份的意味了。

/**
* My method description.  Like other pieces of your comment blocks, 
* this can span multiple lines.
*
* @param {Object} config A config object
* @param {Function} config.callback A callback function on the config object
* @param {Boolean} [extra=false] Do extra, optional work
* @example
* new exampleName(function(){console.log("Hello World")}) 
* @returns {Object} The constructed target object
*/

YUIDoc并非針對Javascript量身定制，因此它有一些用法會讓你使用的時候感到比較別扭。比如最明顯的一個例子就是，YUIDoc并沒有一個專門的方法用來注釋namespace，而是必須使用@class來對namespace進行注釋。
相比之下JSDoc 3和JSDuck都是針對Javascript而設計的，雖然支持的標簽略有差別，但是兩者都能夠很好的支持常見的設計模式。另外，JSDoc 3由于是從JSDoc Toolkit發展而來的，悠久的歷史讓它在Stackoverflow上有很多不錯的例子可以參考。