让文档和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示例地址

注释编写说明