JsDoc

如果你在寫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 >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://m.tkk7.com/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("大家好!","請大家多多關照，謝謝。");