js doc工具推荐及使用（二）：ext-doc

        在项目开发过程中，需要合适的工具来生成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="&lt;i&gt;NOTE: {0}&lt;/i&gt;"/>
        <tag name="demo" title="Demo" format="&lt;a href=&quot;{0}&quot;&gt;{0}&lt;/a&gt;" />        
    </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。 

 

文章来源：http://gogo1217.iteye.com/blog/1164752