仿造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里加上个虚拟目录就搞定了,打开文档,效果如下:

仿造Ext Api Doc打造前端组件在线文档_第1张图片

你可能感兴趣的:(Ajax,json,PHP,css,ext)