在做一些产品时往往需要通过一些工具生成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 定义事件，可以不加在任何变量、函数或者类型上面，但是生成文档的时候如果没有找到拥有事件的类型会有警告提示。