摘要：本文比較了種較為主流的注釋文檔生成工具。應(yīng)該說(shuō)是非常適合開源項(xiàng)目多個(gè)作者共同維護(hù)的一個(gè)文檔工具。最后我選擇了作為文檔生成的工具。為了支持多種語(yǔ)言，它僅對(duì)注釋塊內(nèi)部的內(nèi)容進(jìn)行解析。

最近隨著寫Node以及獨(dú)立的CommonJS模塊越來(lái)越多，我發(fā)現(xiàn)有一份好的文檔不僅可以幫助自己在應(yīng)用這些接口的時(shí)候不至于迷糊，而且對(duì)于共同開發(fā)的情況下，能夠省去大量團(tuán)隊(duì)的交流和Debug的時(shí)間。

本文比較了5種較為主流的Javascript注釋文檔生成工具。需要指出的一點(diǎn)是，Javascript是一個(gè)極為靈活的語(yǔ)言，文檔生成并不像Java那樣具有絕對(duì)統(tǒng)一的規(guī)范，還要根據(jù)使用場(chǎng)景確定哪個(gè)工具更加適合。

JSDoc 3

YUIDoc

Dox

Docco

JSDuck

生成文檔的易讀性

工具的可擴(kuò)展性

注釋語(yǔ)法標(biāo)準(zhǔn)

注釋語(yǔ)義的豐富程度

對(duì)沒有興趣了解細(xì)節(jié)比較的你，可以快速瀏覽下面的總結(jié)來(lái)了解這些工具。

YUIDoc是YUI的附屬項(xiàng)目。YUI團(tuán)隊(duì)希望這個(gè)文檔工具不僅僅可以支持Javascript，而是更多的腳本語(yǔ)言，因此它并不考慮實(shí)際的代碼實(shí)施細(xì)節(jié)，而只是對(duì)注釋部分進(jìn)行了掃描。從好的一面來(lái)說(shuō)，如果你同時(shí)使用了Ruby/PHP/Python等等，YUI或許是一個(gè)比較適合的工具。從反面來(lái)說(shuō)，因?yàn)樗鼪]有考慮實(shí)施細(xì)節(jié)，你需要額外的變量聲明、同時(shí)生成的文檔有可能會(huì)和實(shí)際的實(shí)施細(xì)節(jié)不吻合。

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

Dox是一個(gè)非常輕量級(jí)和可以定制化的工具，它使用和JSDoc 3兼容的注釋語(yǔ)法標(biāo)準(zhǔn)，并將其轉(zhuǎn)化成JSON格式。因此在呈現(xiàn)方式上具有比JSDoc 3更強(qiáng)的可定制性，當(dāng)然也意味著你初期的麻煩會(huì)比較多。

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

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

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

YUIDoc
YUIDoc提供了非常清晰的文檔格式。不僅對(duì)象內(nèi)部的內(nèi)容非常清晰，而且相互引用的link也工作的非常好。同時(shí)YUIDoc提供了全局搜索的功能，你可以容易根據(jù)關(guān)鍵詞找到對(duì)應(yīng)的內(nèi)容。

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

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

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

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

JSDoc 3
JSDoc 3屬于完全開源的項(xiàng)目，因此如果你等不及社區(qū)的更新，你完全可以自己對(duì)JSDoc進(jìn)行深度的開發(fā)。JSDoc對(duì)外提供的開發(fā)接口有3個(gè)：

模版Template

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

插件Plugins

更加詳細(xì)的內(nèi)容則可以在JSDoc的使用說(shuō)明上找到詳細(xì)的講解。

最早這一票是投給JSDoc的，但是經(jīng)過(guò)實(shí)際的測(cè)試之后發(fā)現(xiàn)JSDoc的語(yǔ)法標(biāo)準(zhǔn)非常嚴(yán)格，稍微不符合它的解析規(guī)則JSDoc便不能夠正確的生成文檔，其中最讓我不能接受的事情是它對(duì)于立刻執(zhí)行函數(shù)IIFE的支持實(shí)在是％……&＊&＊……％（里面定義的內(nèi)容大多被認(rèn)為是不暴露在全局中的，非常不方便）
下面的說(shuō)明中我給出了注釋一個(gè)函數(shù)的詳細(xì)示例。

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

        return this;
    }

從這個(gè)簡(jiǎn)單的例子上幾乎不太能看出來(lái)三者實(shí)現(xiàn)的差別，但是當(dāng)你要注釋命名空間、AMD或者CommonJS模塊的時(shí)候，三者的差別就會(huì)凸顯出來(lái)了。此外要聲明的一點(diǎn)是，三者的語(yǔ)法幾乎是不能通用的。我曾經(jīng)試著將用YUIDoc注釋的文件使用JSDoc解析，結(jié)果非常悲劇，反之亦然。

YUIDoc
YUIDoc為了支持多種語(yǔ)言，它僅對(duì)注釋塊內(nèi)部的內(nèi)容進(jìn)行解析。這意味著你需要對(duì)于函數(shù)、類、命名空間等的名稱和更多的內(nèi)容進(jìn)行顯性的聲明。此外，就像前文提到的，它可能會(huì)造成文檔和代碼實(shí)現(xiàn)的不一致，甚至對(duì)于接口的使用造成不好的影響。
YUIDoc對(duì)于注釋內(nèi)容要求嚴(yán)格的兩層結(jié)構(gòu)：Primary Tag和Secondary Tag
詳細(xì)的YUIDoc支持的語(yǔ)法標(biāo)簽可以參考這里

/**
* 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在這點(diǎn)上恰好處在YUIDoc和JSDoc 3之間。它既對(duì)代碼的實(shí)現(xiàn)進(jìn)行了最基本的解析，從中獲取對(duì)應(yīng)的名稱、變量，有效的減少了Tag的使用。同時(shí)又不像JSDoc 3那樣嚴(yán)格，我嘗試了CommonJS、AMD和IIFE都能夠非常自然的生成對(duì)應(yīng)的文檔。
詳細(xì)的JSDuck支持的語(yǔ)法標(biāo)簽可以參考這里

/**
* My method description.  Like other pieces of your comment blocks, 
* this can span multiple lines.
*
*     new exampleName(function(){console.log("Hello World")})  JSDuck支持Markdown格式，插入代碼示例非常簡(jiǎn)單
*
* @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可以支持返回對(duì)象的詳細(xì)結(jié)構(gòu)注釋
*/

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

/**
* 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并非針對(duì)Javascript量身定制，因此它有一些用法會(huì)讓你使用的時(shí)候感到比較別扭。比如最明顯的一個(gè)例子就是，YUIDoc并沒有一個(gè)專門的方法用來(lái)注釋namespace，而是必須使用@class來(lái)對(duì)namespace進(jìn)行注釋。
相比之下JSDoc 3和JSDuck都是針對(duì)Javascript而設(shè)計(jì)的，雖然支持的標(biāo)簽略有差別，但是兩者都能夠很好的支持常見的設(shè)計(jì)模式。另外，JSDoc 3由于是從JSDoc Toolkit發(fā)展而來(lái)的，悠久的歷史讓它在Stackoverflow上有很多不錯(cuò)的例子可以參考。