利用jsdoctoolkit生成javascript文档

在做一些产品时往往需要通过一些工具生成API文档供第三方开发人员查阅。在这里我主要讲述的是基于jsdoc-toolkit如何生成javascript文档、编写javascript时应当如何编写符合jsdoc-toolkit可阅读的注释。
首先下载jsdoc-toolkit => http://code.google.com/p/jsdoc-toolkit/，解压缩到任意目录。建议编写一个批处理方便生成文档：java -jar jsrun.jar app/run.js -a -p -t=templates/jsdoc js/*.js（-p用来输出@private修饰的变量、函数、类型），然后在jsdoc-toolkit目录创建一个js目录，只需要将要生成注释的js放到该目录下。

关于更详细的标签可以到http://code.google.com/p/jsdoc-toolkit/w/list/查看，下面举例说明一些常用标签。

1、定义js文件描述、版本号等

1 /**
2 @fileOverview
3 @version 1.0.0.1
4 */

2、定义namespace

1 /** @namespace */
2 var System = {};

3、声明静态函数

 1 /**
 2 @static
 3 @param {Object} value 值
 4 @return {Int32}
 5 @description 转换为Int32
 6 @example
 7 var n = 0;
 8 var n2 = System.Convert.ToInt32(n);
 9 */
10 System.Convert.ToInt32 = function(value) {
11 
12 }

@static 表示静态
@param 描述参数，格式为@param {[参数类型]} [参数名称] [参数注释]
@return 描述返回值，格式为@return {[参数类型]} [返回值注释]
@description注释
@example 示例

4、忽略定义

1 /** @ignore */
2 var System.Core = {};

5、定义常量

1 /**
2 @field
3 @constrant
4 @type Int32
5 @description 无效值
6 */
7 var NULL = 0;

6、定义类型

 1 /**
 2 @class 字符串
 3 @constructs
 4 @param {String} input 字符
 5 @augments System.Object
 6 @exports String as System.String
 7 */
 8 var String = function(input) {
 9 
10 }

@class 声明类型
@constructs 声明构造函数，如果是含参构造函数需要添加@param
@exports 可以是类型的导出，也可以是别名。如果String没有添加@exports生成的文档类型名称是String，如果添加@exports的定义文档里类型名称就是System.String。
@augments 在声明类型的时候等于@extend，表示继承关系。这里System.String继承于System.Object。

7、成员函数

 1 /**
 2 @public
 3 @param {String} input 输入
 4 @return {Int32}
 5 @description 判断输入字符在当前字符中的起始索引
 6 @example
 7 var str = new System.String(“hello, world”);
 8 var index = str.indexOf(world);
 9 */
10 System.String.prototype.indexOf = function(input) {
11 
12 }

@public 定义成员函数的访问级别，@private代表私有

8、过期声明

 1 /**
 2 @public
 3 @param {String} input 输入
 4 @return {Int32}
 5 @description 判断输入字符在当前字符中的起始索引
 6 @deprecated 使用indexOf2代替indexOf
 7 @example
 8 var str = new System.String(“hello, world”);
 9 var index = str.indexOf(world);
10 */
11 
12 System.String.prototype.indexOf = function(input) {
13 
14 }

@deprecated 描述当前变量、函数或者类型定义已经过期。格式为@deprecated [注释]

9、定义事件

 1 /**
 2 @name System.String#Disposed
 3 @event
 4 @param {System.String} sender 发送方
 5 @param {System.EventArgs} e 事件参数
 6 @description 销毁
 7 @example
 8 var str = System.String(“hello, world”);
 9 
10 str .add_handler(“Disposed”, function(sender, e) { });
11 */

@event 定义事件，可以不加在任何变量、函数或者类型上面，但是生成文档的时候如果没有找到拥有事件的类型会有警告提示。