ext-doc生成方法详解

一、       文件部署说明

1.            资源下载说明

Ext-doc：http://code.google.com/p/ext-doc/

备注：extjs的doc文档自动生成工具

2.            步骤说明

1.         下载ext-doc-1.0.131并解压

2.         打开ext-doc-1.0.131/sample/, 根据控件的命名空间创建文件夹，如：’izpc/form/’，并将需要生成文档的js文件按照命名空间拷贝到相应位置下。

3.         在ext-doc-1.0.131/sample文件夹下的ext.xml中的“<sources>”之后加入“<source src="izpc" match="*.js"/>”

4.         运行ext-doc-1.0.131/sample文件夹下的ext-doc.bat。

5.         到ext-doc-1.0.131文件夹下找到output文件夹并将其拷贝出来，放到服务器下即可浏览。

二、       Ext-doc写法

1.            类名注释：

以“/**”开始，以“*/”结束，其中用@标出关键字，

@class用于标注该类所属的包和该类类名

@extends用于标注该类所继承的类名

例：

/**

 * @class izpc.ContentPanel

 * @extends Ext.Panel

 * @xtype ContentPanel

 */

 

效果图：

2.            Html注释：

在<pre><code>和</code></pre>中内嵌代码。

例：

         <pre><code>

         var tab1 = new izpc.ContentPanel({

                            title: '',

                            id : '',

                            closable: true,

                            params: {taskId: '123123'},

                            autoLoad: {url: '', scripts: true}

                   });

         </code></pre>

 

效果图：

 

3.            配置项注释：

在配置项说明前面加上“@cfg”，之后加上配置项的类型，用{}来框起来，之后是配置项名称，最后加上配置项的说明

 

例：

         /**

     * @cfg {Boolean}  autoScroll

* True to auto scrolling

     */

autoScroll: true,

 

 

效果图：

4.            属性注释：

在属性名前面加上“@Property”，在属性的类型前面用“@type”

例：

/**
     * If true, the items on the axis will be drawn in opposite direction.
     *
     * @property reverse
     * @type Boolean
     */
    reverse: false,

效果图：

5.            方法注释：

在需要说明的函数上面书写注释，@param用以标注输入参数，{}中书写输入参数类型；@return用来标注返回参数，{}中书写返回参数类型。可以在@param之前写出函数注释

 

例：

         /**

     * 得到某个参数.

          * @param {String}

     * @return {Mixed}

     */

         getParam: function(name){

                   return this.params[name] || '';

         },

 

效果图：

6.            事件注释

在“this.addEvents(”里面书写自己属性，在属性名的上面加上注释，在@event后面加上event的名称，在@param 后面加上传入参数，参数类型写在{}里面。

例：

this.addEvents(

         /**

          * @event beforerefresh

          * Fires before a refresh to the chart data is called.  If the beforerefresh handler returns

          * @param {Chart} this

          */

         'beforerefresh')

效果图：

7.            注意事项

1.         最好在生成文档之前删除ext-doc-1.0.131文件夹下的output文件夹，不然会有意向不到的错误；

2.         最好在查看生成文档之前清空cache，不然会有意想不到的错误；

3.         编码格式为ANSI码，否则会出现中外乱码问题。

4.         在生成文档的文件中最好不要出现重复的类定义，否则要在ext-doc-1.0.131/output/output/tree.js中删除重复项。