首页 > 代码库 > 让文档和Demo生成更加简单和强大 - SmartDoc 0.1.1 说明
让文档和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示例地址
注释编写说明
让文档和Demo生成更加简单和强大 - SmartDoc 0.1.1 说明