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

版权所有，转载请注明来源http://gogo1217.iteye.com，违者必究！

 

     之前在整理公司框架的时候，曾经为javascript写过一些注释，但没有合适的工具来生成doc文件。后来功过google以及自己试用，发现jsdoc-toolkit和ext-doc2个工具比较有意思。

jsdoc-toolkit详见：js doc 工具推荐及使用（一）：jsdoc-toolkit

 

ext-doc

 

官方地址为：http://code.google.com/p/ext-doc/

1.下载解压后，目录如下图所示：

其中sample是自带的示例，ext.xml是配置文件，ext-doc.bat是java命令调用;template是doc模板.

 

2.在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;
	}
});

 

3.修改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>

 

 

4.运行sample/ext-doc.bat。在output中生成了相关的doc文档。在web中运行index.html。效果如下：

 

 

注意：截至到ext-doc-1.0.131版本还不能自定义的js的编码，通过查看源码，只能使用系统默认编码，即在windows下需要将js文件的编码设置为gbK,但到发稿时，在svn上发现已经有相关修改，但是svn还是缺少几个文件不能正常编译。

需在web环境中才能正常查看doc。

 

本文中的实例工程打包下载：

http://dl.iteye.com/topics/download/7b8f74f5-28b6-37bf-a3b7-bd8bb6a00bf4

 

评论

6 楼 云霄漫步 2014-02-21  

有没有chm格式的文件？

5 楼 gogo1217 2013-01-06  

javatozhang 写道

我把生成的文件放到tomcat下边，打不开呀？

我在我的机器上测试了下，没有任何问题，下载后直接运行的的sample/ext-doc.bat(mac机器直接修改文件类型为sh)，运行后会在output中生成文件，将整个文件夹拷贝到tomcat的webapps，启动tomcat后,在地址栏输入http://localhost:8080/output/（如果没有修改端口号），就可以看到界面了

4 楼 javatozhang 2012-12-13  

我把生成的文件放到tomcat下边，打不开呀？

3 楼 vvgr 2012-11-23  

这个比toolkit生成出来的漂亮

2 楼 gogo1217 2012-10-12  

需要在web应用服务器中运行，不能直接使用浏览器打开index.html，

1 楼 Yakecan 2012-09-27  

啥情况 ，连下下来的demo里面的index都运行不起来