五分鐘玩轉(zhuǎn)文檔化工具JSDuck

rickchen 發(fā)布于2019-08-21 18:41 / 1912人閱讀

摘要：我們在對現(xiàn)在較主流的五個文檔工具分別作了調(diào)研和嘗試，得到結(jié)論如下工具優(yōu)點缺點提供了完整的模板開發(fā)事件觸發(fā)等接口，使用非常靈活。至此，的環(huán)境部署已經(jīng)全部完成了。

字?jǐn)?shù)：981

閱讀時間：5分鐘

選型依據(jù)

? 在經(jīng)歷了數(shù)個上線的項目之后，筆者所在的團隊已經(jīng)沉淀了一個相對穩(wěn)定版本的前端框架。因此，我們需要出具一套框架API文檔，以便公司其他成員的使用和框架的后期維護。我們在對現(xiàn)在較主流的五個文檔工具：JSDoc 3、YUIDoc、Dox、Docco、JSDuck分別作了調(diào)研和嘗試，得到結(jié)論如下：

工具	優(yōu)點	缺點
JSDoc3	提供了完整的模板開發(fā)、事件觸發(fā)等接口，使用非常靈活。	對代碼要求比較嚴(yán)格，學(xué)習(xí)曲線較高。
YUIDoc	不止支持JS語言，更加抽象，如果同時使用了 Ruby/PHP/Python等語言YUI都可以使用。	功能更加抽象，具體實現(xiàn)方面考慮不全。
Dox	輕量級、高度可定制化，兼容JSDoc3語法。	后期會有較多問題需要自己解決。
Docco	行間注釋方式，更注重實現(xiàn)過程的文檔	不太適合API注釋
JSDuck	代碼實時修改、語法靈活、支持MarkDown語法，支持查看源碼并且文檔可讀性較高，最主要的是上手非常快。	可定制化支持不足，略顯臃腫。

? 我們選型的條件權(quán)重由高到低依次是：

? 1.較強的可讀性。

? 2.較低的學(xué)習(xí)成本。

? 3.注釋語義的豐富程度，是否滿足我們的需求。

? 4.是否足夠靈活。

? JSDuck可讀性較高，上手較快，并且使用JSDuck工具生成的extJS文檔的成功有目共睹，綜合考量，我們最終選擇了JSDuck工具。

環(huán)境部署

? 由于JSDuck需要依賴ruby環(huán)境，所以環(huán)境部署分為以下三步：

? 1.安裝ruby

? 2.安裝devkit

? 3.安裝JSDuck

? 第一步，安裝ruby ：

? 下載地址：https://rubyinstaller.org/dow...

? 選擇符合本機電腦的安裝包下載即可。

? 第二步，安裝devkit：

? 下載地址：https://rubyinstaller.org/dow...

? 選擇符合本機電腦的安裝包下載即可。注意devkit安裝目錄不要有中文或者特殊字符，然后在安裝根目錄下執(zhí)行cmd命令 ruby dk.rb init。這時，我們會在當(dāng)前目錄下看到一個config.yml文件，編輯該文件，添加ruby目錄配置。例如，筆者的ruby是安裝在 F:/Ruby22-x64 目錄下，就做如下圖修改即可：

? 安裝成功后，執(zhí)行命令 ruby dk.rb install 命令。

? 第三步：安裝JSDuck

? 執(zhí)行命令 gem install jsduck 命令安裝jsduck。

? 至此，JSDuck的環(huán)境部署已經(jīng)全部完成了。

第一個文檔

? 準(zhǔn)備工作終于做完了，那還等什么，當(dāng)然是馬上開始看看我們成果如何啦！

? 在 G:test-jsduck目錄下，創(chuàng)建一個test.js文件，編寫如下代碼：

/**
 * @class 人類
 * @author lsjcoder
 * @docauthor lsjcoder
 */
function People(){
    /**
     * 
     * @property {String} 姓名
     */
    this.name = "lsjcoder";

    /**
     * 吃飯
     * @method
     * @param food {String} 食物名稱
     * @return {Boolean}  是否吃過
     */
    this.eat = function(food){
        if(food != null){
            return true;
        }else{
            return false;
        }
    }
}

? 然后在cmd中運行命令 jsduck "G:test-jsducktest.js" --output=G:test-jsduckdoc ，工具就自動將文檔生成到目錄 G:test-jsduckdoc 下，直接運行里面的 index.html 文件就可以看到如下成果圖：

? 是不是非常簡單粗暴且可讀性爆表呀！筆者會在接下來的系列文章中詳細介紹JSDuck的所有技術(shù)，并且最后會將筆者公司在JSDuck中前端框架的實踐以案例的形式分享給大家，敬請期待哦！