仿造Ext Api Doc打造前端组件在线文档
项目中的前端组件已达到一定规模，平时常常有开发人员来询问我组件的用法，并且已存在很多由于使用不当造成的问题，因此有必要出一份前端组件的使用文档，方便别人，也方便自己。
使用什么样的格式让我费了不少脑筋，使用word不方便别人索取和自己更新；使用wiki，不方便自己编写；使用普通的html，成本很高。觉得如果能做一个类似于Ext Api Doc那样的文档就很不错，使用它很方便，不光能建立起类与类的层级关系，还有很强的搜索功能。隐约感觉Ext Api Doc不是专门用Ext开发出来，而是通过源码里的注释自动生成出来，因为Ext源码里的文档和Doc是一一对应的。所以现在需要做的就是，按照一定的格式完善注释，另外要找到这么一个自动从注释生成Ext类型文档的工具。
通过一番搜索，还真找到这么一个工具，http://www.extjs.com/forum/showthread.php?t=55214，此工具使用起来很方便，但需要注意的是运行它需要jdk1.6，怎么使用看看readme就很清楚了。
接下来，就是要按规定格式完善注释了，重点需要做以下几点：
1）class
需要在每个类前加上注释，标明类的相关信息，例如：
/**
* @class Ext.plugins.AccountSelector2
* @extends Ext.plugins.BaseSelector
* 科目选择控件
* @alias Ext.plugins.AccountSelector2
* @author [email protected]
*/
Ext.plugins.AccountSelector2 = function(config){
......
}
其中@class为类名，@extends为继承的基类，@alias为别名，@autho为作者。
2）cfg
需要在类的每个配置属性前加上注释，大家使用组件最关心这个组件的配置属性，例如：
/**
* @cfg {Number} width
* 控件宽度，default:420
*/
其中width为属性名，Number为属性类型
3）@method
需要在类方法前加上注释，例如：
/**
* 修改某个值引起联动
* @method updateAmount
* @param {String} changeField 引发联动的字段(qty、price、disRate、withTax、taxRate、withoutTax)
* @param {String} newValue 改变后的值
* @param {record} r record
* @param {json} defaultValue 默认值
*/
updateAmount:function(changeField,newValue,r,defaultValue){
......
}
4）@property
需要在类属性前加上注释，例如：
/**
* combobox控件
* @type Ext.form.ComboBox
* @property editor
*/
其中 @property为属性名，@type为属性类型
5）@event
在事件侦听前加上注释，例如
/**
* @event beforeaction
* Fires before action event. Return false to cancel the subsequent action event.
* @param {Ext.grid.GridPanel} grid
* @param {Ext.data.Record} record Record corresponding to row clicked
* @param {String} action Identifies the action icon clicked. Equals to icon css class name.
* @param {Integer} rowIndex Index of clicked grid row
* @param {Integer} colIndex Index of clicked grid column that contains all action icons
*/
'beforeaction'
通过对以上五类元素加上注释后，再用工具自动生成，一份很方便和漂亮的文档就出来了，但此文档不能直接打开，得部署到web服务器上，因为此文档的实现用了Ajax，不过这个也很容易，在apache里加上个虚拟目录就搞定了，打开文档，效果如下：