五分鐘玩轉文檔化工具JSDuck

時間 2019-11-10

標籤五分 5分文檔工具 jsduck 简体版

原文原文鏈接

字數：981 javascript

閱讀時間：5分鐘html

選型依據

在經歷了數個上線的項目以後，筆者所在的團隊已經沉澱了一個相對穩定版本的前端框架。所以，咱們須要出具一套框架API文檔，以便公司其餘成員的使用和框架的後期維護。咱們在對如今較主流的五個文檔工具：JSDoc 三、YUIDoc、Dox、Docco、JSDuck分別做了調研和嘗試，獲得結論以下：前端

工具	優勢	缺點
JSDoc3	提供了完整的模板開發、事件觸發等接口，使用很是靈活。	對代碼要求比較嚴格，學習曲線較高。
YUIDoc	不止支持JS語言，更加抽象，若是同時使用了 Ruby/PHP/Python等語言YUI均可以使用。	功能更加抽象，具體實現方面考慮不全。
Dox	輕量級、高度可定製化，兼容JSDoc3語法。	後期會有較多問題須要本身解決。
Docco	行間註釋方式，更注重實現過程的文檔	不太適合API註釋
JSDuck	代碼實時修改、語法靈活、支持MarkDown語法，支持查看源碼而且文檔可讀性較高，最主要的是上手很是快。	可定製化支持不足，略顯臃腫。

咱們選型的條件權重由高到低依次是：java

1.較強的可讀性。ruby

2.較低的學習成本。前端框架

3.註釋語義的豐富程度，是否知足咱們的需求。框架

4.是否足夠靈活。工具

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

環境部署

因爲JSDuck須要依賴ruby環境，因此環境部署分爲如下三步：this

1.安裝ruby

2.安裝devkit

3.安裝JSDuck

第一步，安裝ruby ：

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

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

第二步，安裝devkit：

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

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

安裝成功後，執行命令 ruby dk.rb install 命令。

第三步：安裝JSDuck

執行命令 gem install jsduck 命令安裝jsduck。

至此，JSDuck的環境部署已經所有完成了。

第一個文檔

準備工做終於作完了，那還等什麼，固然是立刻開始看看咱們成果如何啦！

在 G:test-jsduck目錄下，建立一個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的全部技術，而且最後會將筆者公司在JSDuck中前端框架的實踐以案例的形式分享給你們，敬請期待哦！