讓文檔和Demo生成更加簡單和強大 - SmartDoc 0.1.1 說明

新特性

smartDoc 0.1.1版正式發布，其中加入了更多方便生成文檔的功能，主要特性如下：

* 加入@demo配置項，看可以動態抓取html和js的內容作為@example，同時支持擴展@demo讀取
* 支持jasmine測試js文件的單元代碼抓取為@example
* 實現多個example顯示和tab切換
* 加入@show配置項來控制直接顯示example效果
* 主題改版
* 去除@attribute屬性設置，統一使用@property；

 

docConfig新增配置：

//demo掃描目錄
demoDir: "",

 //demo生成器地址
demoBuilder: './demoBuilder.js',

//demo代碼生成器地址
codeLoader: './jasmineLoader.js'

 

新版效果片段如圖：

詳細說明

　　example與code分離

　　　　1. 以前的@example都需要寫在代碼注釋當中，很影響代碼的可讀性；新版中加入@demo配置，通過設置文件路徑，可以自動讀取html或者js文件生成@example；

原來的寫法：	現在的寫法：
/** * ................ * @method getTargets3 * @example * var bar; .... */	/** * ................ * @method getTargets3 * @demo inherit/getTargets3.js */

 　　　　　　inherit/getTargets3.js 會讀取定義在docConfig文件demoDir配置下的文件然后生成@example

　　　　　　

      Jasmine的單元測試代碼的讀取重用

　　　 支持jasmine測試js文件的單元代碼的讀取，減少而外開銷。不過同時需要注意的事情是盡量編寫測試用例的時候，每個單元盡量獨立，不要使用全局變量；

　　　　例如：

　　　　

/**
     * Deferred對象
     * @class Deferred
     * @constructor
     * @demo st/deferred.js [resolve]
     */
    function Deferred() {

    }

 

　　 jasmine測試代碼deferred.js：

　　

describe('Deferred', function() {
        it("resolve",function(testDone){
            var defer = st.Deferred();

            function test(){
                setTimeout(function(){
                    defer.resolve("test");
                })
                return defer.promise();

            }

            st.when(test()).done(function(result){
                expect(result).toBe('test');
                testDone();
            })
        })
..........

 

 　　st/deferred.js [resolve] 對應的就是代碼中的it("resolve",fn)的內容,文件地址后面的[...]表示jasmine的文件單元測試項，最終效果如下：

　　　　　　

　　　　

　支持@demo解析和讀取自定義

      jasmine的是通過內置的jasmineLoader去解析代碼的，同時可以自定義代碼解析規則 - docConfig的demoBuilder和codeLoader

 

　支持頁面直接顯示@demo/example；同時也支持tab顯示多個；

　　例子中配置了多個@demo，同時在@demo中文件路徑的配置加入了{...}，表示tab的標題，，如果沒有設置則取文件名；@show表示直接在頁面上顯示結果

/**
     * ui測試類； 
     * @class UI
     * @constructor
     * @content {string} type 內容
     * @demo ui.html
     * @demo ui2.html {ui測試2}
     * @show true
     */        
    function UI(content){
        this.init(content);
    }

 

效果如下：

 

 

結尾

smartdoc還在持續建設中，大家使用中有什么問題和建議，可以直接使用 git的issue 反饋給我。

相關鏈接如下：

SmartDoc地址

doc示例地址

注釋編寫說明