在项目开发过程中,需要合适的工具来生成doc文件,通过google以及试用,发现jsdoc-toolkit和ext-doc2个工具比较有意思。
下面详细介绍下ext-doc在实际工程中的应用
官方地址为:http://code.google.com/p/ext-doc/
一.下载解压后,目录如下图所示:
其中sample是自带的示例,ext.xml是配置文件,ext-doc.bat是java命令调用;template是doc模板。
二.在sample下新建extdoc-demo.js,代码如下:
/** * 基础组件,其他组件应该继承本class * @class BaseComponent */ BaseComponent = extend(Observable, { /** * 构造方法 * @param {JSONObject} cfg */ constructor : function(cfg) { this.setConfig(cfg); //设置属性 if(!this.getParameterScope()) { this.addParameterScope('default'); } if(!this.getParameterScope('post')) { this.addParameterScope('default', 'post'); } this.initComponent(cfg); //调用初始化组件 }, /** * 初始化组件 */ initComponent : function() { this.render(); }, /** * 是否已经渲染 */ isRendered : false, clazz : 'BaseComponent', /** * 如果指定了renderTo属性,则自动渲染,否则需要显示指定渲染目标 * @param {String} renderTo 渲染容器id */ render : function(renderTo) { if(!this.isRendered) { this.renderTo = renderTo || this.renderTo; if(this.renderTo) { //执行渲染之前的函数 if(this.fireEvent('beforerender', this.renderTo)) { if(this.fireEvent('onrender', this.renderTo)) { this.isRendered = true; this.fireEvent('afterrender', this.renderTo); } } } } }, /** * 重新加载 * @param {Object} params 参数 * @param {String || Array} eventScope 事件作用域,用于组件之间传递事件 * @param {Object} trigerHander 事件发起的组件对象 */ load : function(params, eventScope, trigerHander) { }, /** * 预览,如果当前不是编辑模式,则不会触发任何操作 * */ preview : function() { if(this.isEditMode()) { if(this.fireEvent('beforepreview')) { if(this.fireEvent('onpreview')) this.fireEvent('afterpreview'); } } }, /** * 编辑,如果当前不是编辑模式,则不会触发任何操作 */ edit : function() { if(this.isEditMode()) { if(this.fireEvent('beforeedit')) { if(this.fireEvent('onedit')) this.fireEvent('afteredit'); } } }, /** * 拖拽放下事件 */ drop : function(event, data) { if(this.fireEvent('beforedrop', event, data)) { if(this.fireEvent('ondrop', event, data)) this.fireEvent('afterdrop', event, data); } }, /** * 移除组件 */ remove : function() { if(this.isEditMode()) { if(this.fireEvent('beforeremove', this)) { if(this.fireEvent('onremove', this)) this.fireEvent('afterremove', this); } } }, onload : function(params) { if(this.renderTo && this.mvId) { var thiz = this, params = params || {}; jQuery('#' + this.renderTo).load(this.extURL + '?returnJsp=false&mvid=' + this.mvId, params, function() { thiz.fireEvent('afterload', params); }); } }, onrender : function() {this.isEditMode() ? this.edit() : this.load(); }, /** * 对象销毁,本方法需要组件将当前对象的缓存属性,额外的dom对象,绑定的时间删除。 */ destroy : function() { delete this._eventCalls; }, equals : function(obj) { return obj && this.renderTo == obj.renderTo; } });
三.修改sample下的ext.xml,增加自定义的js目录。如下所示:
<?xml version="1.0" encoding="UTF-8"?> <doc> <!-- Source section (required) Use <source> to specify directory with JavaScript source files to be processed or just one JS file. Directories are processed recursively. Attributes: src: (required) - source directory name or file name match: (optional) - wildcard for the files. Default: "*.js" skipHidden: (optional) - True to skip processing files and directories with hidden attribute. Default: true. Custom tags section(optional) Tags to be added to the list of custom tags, for every "documantable item" i.e. class, cfg, property, event. Custom tag list is accessible in XSLT-template and has two properties: title and value. name: (required) tag name. ex: "author" => "@author" title: (optional) title of custom tag format: (optional) pattern string used for formatting value Usage example: XML: <tag name="author" title="Author"/> JS: /** * @class MyClass * @author I'm the * author */ XSLT: <xsl:if test="customTags"> <b><xsl:value-of select="customTags/title"/></b> : <xsl:value-of select="customTags/value"/> </xsl:if> Resulting HTML: <b>Author</b>:I'm the author --> <sources> <!-- <source src="ext/source" match="*.js"/> --> <!--<source src="ext" match="Ext*.js"/>--> <!--<source src="sample.js" /> --> <source src="demo" match="*.js"/> </sources> <tags> <tag name="author" title="Author"/> <tag name="version" title="Version"/> <tag name="note" format="<i>NOTE: {0}</i>"/> <tag name="demo" title="Demo" format="<a href="{0}">{0}</a>" /> </tags> </doc>
四.运行sample/ext-doc.bat。在output中生成了相关的doc文档
五.在web中运行index.html,效果如下:
新建web工程ext-doc-view,将output下生成的文件拷入到工程中。
运行效果:
注意:
1.截至到ext-doc-1.0.131版本还不能自定义的js的编码,通过查看源码,只能使用系统默认编码,即在windows下需要将js文件的编码设置为gbK,但到发稿时,在svn上发现已经有相关修改,但是svn还是缺少几个文件不能正常编译。
2.需在web环境中才能正常查看doc。