JS文档构建(jsdoc)

一、命令分类
类定义
@class    类型定义
@version    版本信息
@author    作者

@constructor    构造方法
@description    描述
@example    示例
@param

/**
     * @name Tabs
     * @author Halen
     * @class  页签组件
     * 
     * @constructor
     * @description 构造函数. 
     * @param p
     */
Tabs = function(p) {
}

属性定义
@default    默认值
@type    类型
@description    描述
@example    示例

/**
    *是否懒加载。
    * @default false
    * @type Boolean
    * @example
    * var tabs = new Tabs({lazyLoad:false});
    */
 lazyLoad : false,

方法定义
@param    默认值
@returns    类型
@description    描述
@example    示例

/**
    * 改变label属性。
    * @name AutoComplete#changeLabel
    * @function
    * @param {String} label 按钮文本
    * @example
    * var autoComplete = new AutoComplete();
    * autoComplete.changeLabel(“new label”);
    */
    changeLabel : function(label){
    }

事件定义
@event    声明为事件
@param    默认值
@returns    类型
@description    描述
@example    示例


强制定义
@field    字段/属性
@function    方法
@event    事件
@name    名称定义


继承相关
@lends
@augments
@borrows


类型相关
@constant
@private
@static
@public
@inner


综合
@deprecated    已过期
@link    引用
@see    引用
@throws    抛出异常
@since    从哪个版本开始生效
@requires    依赖于其他类定义




二、jsdoc的完整命令介绍
http://code.google.com/p/jsdoc-toolkit/w/list

三、使用jsdoc
单独使用Java命令：
java -jar jsrun.jar app/run.js -a -t=templates/jsdoc todocjs/*.js

整合ant命令：

<target name="build-docs" description="build docs">
    <delete dir="${docs.dir}"></delete>
    <mkdir dir="${docs.dir}"/>
    <java jar="${jsdoc.lib.dir}/jsrun.jar" fork="true">
        <arg value="${jsdoc.lib.dir}/app/run.js"/>
        <!-- the path of the jsdoc templates-->
        <arg value="-t=${jsdoc.builder.dir}/jsdoc"/>
        <!-- the source path of the js -->
        <arg value="../ui/"/>
        <!-- the output path of the generated jsdoc -->
        <arg value="-d=${docs.dir}" />
    </java>
</target>

四、jsdoc的一些bug
(1)、@default {} 无法正常显示{}
(2)、如果属性和方法名为同一名称，比如name属性和name()方法，无法同时生成同名字的属性和方法，认为是同一个名称，最后只留一个

参考及案例：
http://ui.operamasks.org/website/demos.html
http://code.google.com/p/jsdoc-toolkit/w/list