JsDoc 介紹

JsDoc <?xml:namespace prefix = o ns = "urn:schemas-microsoft-com:office:office" /?>

如果你在寫javascript，是否羨慕過C++，JAVA的文件自動生成工具？是否希望自己的程式也能自動生成一份對應的文件，猶如java API文件一樣呢？不要再羨慕了。jsdoc_toolkit.zip 一款強大的js doc生成工具已經能完成你所羨慕這些功能了。

你可以訪問該工具的主頁：http://www.jsdoctoolkit.org/ 檢視相關用法。這是一個JAVA開發的開源專案，下面只是記錄一些使用過程中常見的細節：

將下載的 jsdoc_toolkit.zip解壓後，其中的README.txt 有使用說明。 我可不想每次用的時候都去命令下做這些操作，於是我在解壓後的目錄裡新建了一個run.bat 內容編輯如下：

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

根據上面的命令，建立一個目錄，名字為 js 。顯然我們將需要提取文件的js檔案命名為*.js ，並且放在js目錄下，執行run.bat就OK。

什麼這麼簡單？ 對就是這麼簡單，不過，你的js檔案符合jsdoc規範嗎？

如果你發現自己操作起來不是那麼順利，那麼：

http://www.jsdoctoolkit.org/wiki/?page=Tag%20Reference 主頁上的這篇文章對你有所幫助，意思就是你的註釋應該符合他的標準。

有人說我英語太差，好吧。我就把常見的一些註釋規範或者是他jsdoc工具能識別的標識寫出來：

@author:作者

@argument:引數

@augments：引數

@class： 類

@constant：常數

@constructor：構造

@constructs： 構造

@default：預設值

@deprecated： 推薦，說明使用一個變數已不再支援

@description：說明

@example ：範例

@extends： 擴充套件 ，繼承

@field：變數（非功能）

@fileOverview ：整個檔案資訊

@function： 功能 (表示該變數指向一個功能)

@inner || @private : 私有，內部

@ignore： 忽視 （文件生成的式後也將忽視這個變數）

@event：事件

@version：版本

@type：型別 描述預期的型別變數的值或返回值的函式

@throws :可能丟擲的異常

@static： 靜態，訪問該變數不需要例項

@since： 自 （表明某屬性特徵，是在什麼版本之後才有的）

@see： 描述相關的資源

@scope ||@lends： 作用域

@return ||@returns

@requires： 描述必須需要的資源

@public： 說明內在變數是公開的

@property ： 屬性

@param：引數

@namespace： 名稱空間

較多用法如下：

eg:

/**

 * @fileOverview 功能介面呼叫

 * @author -274°C

 * @constructor BlogJava.Data

 * @description [資料結構]名稱空間

 * @see The <a href="http://www.example.com">Example Project</a>.

 * @param  {NULL_PARAMETER} objNull 

 * @param  {Function} [fnCallback="null"] :如果不是函式型別,則進行同步呼叫

 * @return {Boolean} json ：作為回撥引數返回

 * @example new KxEFileMon.Data.NULL_PARAMETER("a")

 */

 

以一個完整例子來演示下效果吧：Test.js 隨手敲的，至於這個指令碼細節就請大家別去考究。

/**
 * @fileOverview 樓主資訊描述
 * @author -274°C
 */
 
 /**
 * @constructor LZInfo
 * @description 自我介紹
 * @see The <a href=" http://www.blogjava.net/JAVA-HE">-274°C</a >.
 * @example new LZInfo();
 */
function LZInfo()
{
 /**
 * @description {String} 姓名
 * @field
 */
 this.Name = "hechangmin";
 /**
 * @description 打招呼
 * @param {String} title  說話標題
 * @param {String} content 說話內容
 * @return {Num} nResult 返回結果
 */
 this.SayHello = function()
 {
   alert( arguments[0] + " my name is " + this.Name + arguments[1]);
 }
}

//var lz = new LZInfo();
//lz.SayHello("大家好!","請大家多多關照，謝謝。");