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文件。