jsDoc使用方法

JsDoc Toolkit 是一個把js描述格式化成文檔的工具。開發者只需按JsDoc的規範寫好註釋就可以很方便導出文檔。它是google 推薦的 JsDoc生成工具。

JsDoc Toolkit不久前發佈了2.3.2版本，主要還是對前版本的修復。 

如果你需要使用Ant，JsDoc還有一個Ant插件：JsDoc Toolkit Ant Task 
下載JsDoc Toolkit2.3.2：http://jsdoc-toolkit.googlecode.com/files/jsdoc_toolkit-2.3.2.zip
命令名描述 
@param @argument 指定參數名和說明來描述一個函數參數 

@returns 描述函數的返回值 
@author 指示代碼的作者 
@deprecated 指示一個函數已經廢棄，而且在將來的代碼版本中將徹底刪除。要避免使用這段代碼 
@see 創建一個HTML鏈接，指向指定類的描述 
@version 指定發佈版本 
@requires 創建一個HTML鏈接，指向這個類所需的指定類 
@throws @exception 描述函數可能拋出的異常的類型 
{@link} 創建一個HTML鏈接，指向指定的類。這與@see很類似，但{@link}能嵌在註釋文本中 
@fileoverview 這是一個特殊的標記。如果在文件的第一個文檔塊中使用這個標記，則指定該文檔塊的餘下部分將用來提供這個文件的概述 
@class 提供類的有關信息，用在構造函數的文檔中 
@constructor 明確一個函數是某個類的構造函數 
@type 指定函數的返回類型 
@extends 指示一個類派生了另一個類。JSDoc通常自己就可以檢測出這種信息，不過，在某些情況下則必須使用這個標記 
@private 指示一個類或函數是私有的。私有類和函數不會出現在HTML文檔中，除非運行JSDoc時提供了--private命令行選項 
@final 指示一個值是常量值。要記住JavaScript無法真正保證一個值是常量 
@ignore JSDoc忽略有這個標記的函數 

JsDoc:是js文檔生成工具，它從javascript程序源代碼中抽取類、方法、成員等註釋信息形成一個和源代碼配套的API幫助文檔。 
Java開源項目http://www.jsdoctoolkit.org/，它是一個功能強大的javascript文檔生成工具。 
下面我們來結束一下如何使用。 
我們通過下載工具類庫。 
這裏我們使用的是jsdoc_toolkit-2.1.0.zip也是當前的最高版本。 
我們將這個文件解壓。可以看到裏面README.txt文件。 
這裏有詳細的使用說明。【好像介紹到這裏就可以了。當然你也可以繼續讀下】 
這裏我們需要通過命令行進行創建javascript文檔。 
java -jar jsrun.jar app/run.js -a -e=GB18030 -t=templates/jsdoc test/*.js 
當然如果感覺通過命令行的方式比較麻煩，我們可以自行創建一個.bat文件 
將上面的內容複製到該文件中，執行即可。 
下面我來簡單解釋一下這其中的參數 
-a 表示全部的方法 
-e 表示對應的文件的編碼根式 這裏對應的是GB18030 默認的是utf-8 
-t 表示生產doc的文檔樣式模板 
這裏的test/*.js表示在test目錄下的全部javascript文件 
執行完畢後將文檔結果默認輸出到/out/jsdoc目錄下。當然這個目錄也是可以定義的 
具體參數可以使用 
java -jar jsrun.jar app/run.js --help 
進行查看。 
結果如下： 

複製代碼代碼如下:

OPTIONS: 
-a or --allfunctions 
Include all functions, even undocumented ones. 
-c or --conf 
Load a configuration file. 
-d=<PATH> or --directory=<PATH> 
Output to this directory (defaults to "out"). 
-D="myVar:My value" or --define="myVar:My value" 
Multiple. Define a variable, available in JsDoc as JSDOC.opt.D.myVar. 
-e=<ENCODING> or --encoding=<ENCODING> 
Use this encoding to read and write files. 
-E="REGEX" or --exclude="REGEX" 
Multiple. Exclude files based on the supplied regex. 
-h or --help 
Show this message and exit. 
-n or --nocode 
Ignore all code, only document comments with @name tags. 
-o=<PATH> or --out=<PATH> 
Print log messages to a file (defaults to stdout). 
-p or --private 
Include symbols tagged as private, underscored and inner symbols. 
-q or --quiet 
Do not output any messages, not even warnings. 

下面我們來創建test下的js文件 
簡單的方法標註 
myjs.js 

複製代碼代碼如下:

/** 
* @fileOverview 簡單的方法標註示例 
* @author <a href="llying.javaeye.com">llying</a> 
* @version 0.1 
*/ 

/** 
* @description 加法運算 
* @param {Num} num1 加數 
* @param {Num} num2 被加數 
* @return {Num} result 結果 
*/ 
function add(num1,num2){ 
return num1 + num2; 
} 
/** 
* @description 減法運算 
* @param {Num} num1 減數 
* @param {Num} num2 被減數 
* @return {Num} result 結果 
*/ 
function minus(num1,num2){ 
return num1 - num2; 
} 

類的方法標註 
myjs2.js 

複製代碼代碼如下:

/** 
* @fileOverview 簡單的類對象標註示例 
* @author <a href="llying.javaeye.com">llying</a> 
* @version 0.1 
*/ 
/** 
* @author llying 
* @constructor Person 
* @description 一個Person類 
* @see The <a href="#">llying</a >. 
* @example new Parent(“張三”,15); 
* @since version 0.1 
* @param {String} username 姓名 
* @param {Num} age 年齡 
*/ 
function Person(username,age) 
{ 
/** 
* @description {Sting} 姓名 
* @field 
*/ 
this.username = username; 
/** 
* @description {Num} 年齡 
* @field 
*/ 
this.age = age 
/** 
* @description 彈出say內容 
* @param {String} content 內容 
*/ 
this.say = function(content) 
{ 
alert(this.username+" say :"+content); 
} 
/** 
* @description 返回json格式的對象 
* @return {String} json格式 
* @see Person#say 
*/ 
this.getJson = function(){ 
return "{name:"+this.username+",age"+this.age+"}"; 
} 
} 

現在我們可以運行java -jar jsrun.jar app/run.js -a -e=GB18030 -t=templates/jsdoc test/*.js 

至此我們的js文檔生成完畢。我們也無需羨慕JavaDoc了。 

我們只是列出了常用的標籤，至於更多的可以登陸到官方網站查看 
http://code.google.com/p/jsdoc-toolkit/wiki/TagReference