jsdoc-toolkit文档工具使用说明

JsDoc Toolkit 是一款辅助工具，你只需要根据约定在 JavaScript 代码中添加相应的注释，它就可以根据这些注释来自动生成API文档。对Java 熟悉的人可能会发现它和 Java 的文档自动化工具 JavaDoc 很像，没错，JsDoc Toolkit 就是基于 JavaDoc 开发的。 项目地址：http://code.google.com/p/jsdoc-toolkit/。

由于 JsDoc Toolkit 是用 Java 编写的，所以运行的时候需要 Java 环境。

1、java jdk安装

2、Apache Ant安装和配置

3、JsDoc Toolkit 安装

去 JsDoc Toolkit 的官方主页下载最新的压缩包，解压之后进入 jsdoc-toolkit 目录（即 jsrun.jar 所在的目录），然后运行下面的命令：

java -jar jsrun.jar app/run.js -a -t=templates/jsdoc app/test.js

如果成功的话，你就会看到当前文件夹里多出了一个叫做 out 的文件夹，生成的文档就在里面了！然后你就可以在浏览器中查看了。如果你想了解 JsDoc Toolkit 的高级用法，可以用下面的命令：

java -jar jsrun.jar app/run.js --help

然后就可以看到一些参数说明，这里简单介绍几个： 

-a 或者 –allfunctions ：为全部函数生成文档，包括那些没有写注释的。 
-c 或者 –conf ：使用配置文件 
-d= 或者 –directory=：指定生成文档的输出目录，默认是 “out” 
-e= 或者 –encoding=：指定编码方式 
-n 或者 –nocode ：忽略所有代码，只为有 @name 标签的注释生成文档。 
-o= 或者 –out= ： 将日志信息输出到指定文件 
-q 或者 –quiet ： 不输出任何信息，包括警告。 
-t= 或者 –template= ：指定文档的模板，这个参数必须提供。

4、JsDoc Toolkit标签简介

在http://code.google.com/p/jsdoc-toolkit/w/list上可以查看详细的说明。下面列出几个常用的标签。附件是一个示例文件。

@class 类

/** Creates a new Person. 
@class Represents a person. 
*/ 
Person = function() { }

@name 名称

/**
* @name hiliteSearchTerm 
* @function
*/ 
eval("window.hiliteSearchTerm = function(term) {};")

@lends 把匿名对象里的所有成员都作为指定类下的成员输出文档

/** @class */ 
var Person = makeClass( 
/** @lends Person.prototype */
{ 
        initialize: function(name) { 
              this.name = name; 
        }, 
       say: function(message) {
             return this.name + " says: " + message; 
        }
} );

@description 描述信息

/** @description Creates a new Person. 
     @constructor 
*/ 
Person = function() { }

@property 属性

方式1：

/**
* @class 
*/ 
function Person(id) { 
/** 
* The id of the person. 
* @type number
*/ this.id = id;
}

方式2：

/** 
* @class 
* @property {number} id The id of the person. 
*/ 
function Person(id) { 
       this.id = id; 
}

@example 示例

/**
* @example
* var bleeper = makeBleep(3); 
* bleeper.flop(); 
*/

5、JsDoc Toolkit Ant Task使用

JsDoc Toolkit Ant Task 是一个Ant 插件，可以方便的使用Ant来生成文档。

要使用JsDoc Toolkit Ant Task ，需要有Rhino engine。下载Rhino 1.6r7版本，注意最新版本有bug，不能使用。解压后把js.jar拷贝到apache-ant安装文件夹的lib目录下。

下载JsDoc Toolkit Ant Task ，把jsdoc-toolkit-ant-task-1.1.0.jar也拷贝到apache-ant安装文件夹的lib目录下。

只需要按照JsDoc Toolkit Ant Task的说明编写build.xml文件即可。

build.xml

<?xml version="1.0" encoding="UTF-8" ?>
<!--ant的所有内容必须包含在这个里边，name是你给它取的名字，basedir是工作的根目录，.代表当前目录。default代表默认要做的事情-->
<project name="MyProject" default="compress" basedir="D:/Program Files/jsdoc-toolkit/">
  <!-- 设置全局变量 -->
  <property name="source" location="source"/>             <!--源代码所在文件夹，相对于basedir的路径-->
  <property name="document"  location="output/jsdoc"/>    <!--文档输出文件夹-->
  <property name="compressdir" location="Scripts"/>       <!--压缩后js文件输出路径-->
  <property name="template" value="jsdoc"/>               <!--生成文档所用模版名称，jsdoc为默认模版-->
  <property name="iscompress" value="true"/>              <!--是否生成压缩文件-->
  
  <!--生成文档-->
  <target name="buildDocument">
    <echo>正在生成帮助文档...</echo>
    <taskdef name="jsdoctoolkit" classname="uk.co.darrenhurley.ant.tasks.JsDocToolkit"/>
    <jsdoctoolkit jsdochome="D:/Program Files/jsdoc-toolkit/" template="${template}" outputdir="${document}" inputdir="${source}">
    </jsdoctoolkit> 
  </target>

  <!--压缩脚本文件-->
  <target name="compress" depends="buildDocument" if="${iscompress}">
    <echo>正在压缩文件...</echo>
    <taskdef name="jsmin" classname="net.matthaynes.jsmin.JSMin_Task"/>
    <jsmin destdir="${compressdir}" force="true">
      <fileset dir="${source}" includes="**/*.js"/>
    </jsmin>
  </target>
</project>

6、JSMin Ant Task

JSMin Ant Task也是一个Ant插件，用来压缩js脚本文件。下载并拷贝jsmin.0.2.4.jar到apache-ant安装文件夹的lib目录下。 使用见build.xml文件。