JsDoc

如果你在寫javascript，是否羨慕過(guò)C++，JAVA的文檔自動(dòng)生成工具？是否希望自己的程序也能自動(dòng)生成一份對(duì)應(yīng)的文檔，猶如java API文檔一樣呢？不要再羨慕了。jsdoc_toolkit.zip 一款強(qiáng)大的js doc生成工具已經(jīng)能完成你所羨慕這些功能了。

你可以訪問該工具的主頁(yè)：http://www.jsdoctoolkit.org/ 查看相關(guān)用法。這是一個(gè)JAVA開發(fā)的開源項(xiàng)目，下面只是記錄一些使用過(guò)程中常見的細(xì)節(jié)：

將下載的 jsdoc_toolkit.zip解壓后，其中的README.txt 有使用說(shuō)明。 我可不想每次用的時(shí)候都去命令下做這些操作，于是我在解壓后的目錄里新建了一個(gè)run.bat 內(nèi)容編輯如下：

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

根據(jù)上面的命令，建立一個(gè)目錄，名字為 js 。顯然我們將需要提取文檔的js文件命名為*.js ，并且放在js目錄下，執(zhí)行run.bat就OK。

什么這么簡(jiǎn)單？ 對(duì)就是這么簡(jiǎn)單，不過(guò)，你的js文件符合jsdoc規(guī)范嗎？

如果你發(fā)現(xiàn)自己操作起來(lái)不是那么順利，那么：

http://www.jsdoctoolkit.org/wiki/?page=Tag%20Reference 主頁(yè)上的這篇文章對(duì)你有所幫助，意思就是你的注釋應(yīng)該符合他的標(biāo)準(zhǔn)。

有人說(shuō)我英語(yǔ)太差，好吧。我就把常見的一些注釋規(guī)范或者是他jsdoc工具能識(shí)別的標(biāo)識(shí)寫出來(lái)：

@author:作者

@argument:參數(shù)

@augments：參數(shù)

@class： 類

@constant：常數(shù)

@constructor：構(gòu)造

@constructs： 構(gòu)造

@default：默認(rèn)值

@deprecated： 推薦，說(shuō)明使用一個(gè)變量已不再支持

@description：說(shuō)明

@example ：范例

@extends： 擴(kuò)展 ，繼承

@field：變量（非功能）

@fileOverview ：整個(gè)文件信息

@function： 功能 (表示該變量指向一個(gè)功能)

@inner || @private : 私有，內(nèi)部

@ignore： 忽視 （文檔生成的式后也將忽視這個(gè)變量）

@event：事件

@version：版本

@type：類型 描述預(yù)期的類型變量的值或返回值的函數(shù)

@throws :可能拋出的異常

@static： 靜態(tài)，訪問該變量不需要實(shí)例

@since： 自 （表明某屬性特征，是在什么版本之后才有的）

@see： 描述相關(guān)的資源

@scope ||@lends： 作用域

@return ||@returns

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

@public： 說(shuō)明內(nèi)在變量是公開的

@property ： 屬性

@param：參數(shù)

@namespace： 命名空間

較多用法如下：

eg:

/**

 * @fileOverview 功能接口調(diào)用

 * @author -274°C

 * @constructor BlogJava.Data

 * @description [數(shù)據(jù)結(jié)構(gòu)]命名空間

 * @see The <a >Example Project</a>.

 * @param  {NULL_PARAMETER} objNull 

 * @param  {Function} [fnCallback="null"] :如果不是函數(shù)類型,則進(jìn)行同步調(diào)用

 * @return {Boolean} json ：作為回調(diào)參數(shù)返回

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

 */

 

以一個(gè)完整例子來(lái)演示下效果吧：Test.js 隨手敲的，至于這個(gè)腳本細(xì)節(jié)就請(qǐng)大家別去考究。

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

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