《编写可维护的 JavaScript》读书笔记第18章：生成文档

1. JSDoc Toolkit

/**
 * @namespace 应用程序单体。
 */
var MyApplication = {
    /**
     * 两个数字的加法
     * @param {int} num1 第一个数字。
     * @param {int} num2 第二个数字。
     * @returns {int} 两个数的和。
     * @static
     */
    add: function (num1, num2) {
        return num1 + num2;
    }
};

JSDoc Toolkit 采用定制的 Rhino 启动器（jsrun.jar）来执行。

语法：

java -jar jsrun.jar app/run.js [file]+ -t=[templates] -d=[directory] [options]

例如：

java -jar jsrun.jar app/run.js core/core.js -t=templates/jsdoc/ -d=./out

通常把配置信息放到属性文件里：

src.dir = ./src
lib.dir = ./lib
jsdoc.dir = ${lib.dir}/jsdoc-toolkit
jsdoc = ${jsdoc.dir}/jsrun.jar
jsdoc.run = ${jsdoc.dir}/app/run.js
jsdoc.templates = ${jsdoc.dir}/templates
jsdoc.output = ./docs

Ant：

<target name="document">
    <apply executable="java" failonerror="true" parallel="true">
        <fileset dir="${src.dir}" includes="**/*.js"/>
        <arg line="-jar"/>
        <arg path="${jsdoc}"/>
        <arg path="${jsdoc.options}"/>
        <arg path="${jsdoc.run}"/>
        <arg line="-t=${jsdoc.templates}"/>
        <arg line="-d=${jsdoc.output}"/>
        <srcfile/>
    </apply>
</target>

2. YUI Doc

略。