隨著 Web2.0 的風(fēng)靡，JavaScript 已經(jīng)成為一門被人們重新認(rèn)識的編程語言，由于大量 JS 開源框架的出現(xiàn)，利用 JavaScript 開發(fā) 的項目越來越多，越來越大。同時，也有越來越多JavaScript 開發(fā)問題暴露出來，如性能、網(wǎng)頁加載速度等，其中，JavaScript 文檔維護也成 為了開發(fā)者亟待解決的一個難題。
許多現(xiàn)代編程語言都有自己的集成化文檔生成工具，像 Java 有 JavaDoc，.NET有 NDoc，PHP有 PHPDoc，這些自動化文檔工具可以根據(jù)代碼中的注釋自動生成代碼文檔。
JsDoc Toolkit 就是這樣一個自動化文檔工具，它是發(fā)布在 Google code 上的一個開源項目，和其他語言的文檔工具一樣，它可以自動從 JavaScript 代碼中提取注釋生成格式化文檔。
下載地址
http://code.google.com/p/jsdoc-toolkit/downloads/list
運行環(huán)境
JsDoc Toolkit是用Java開發(fā)的，運行時需要 Java 1.5+。
用法
在運行之前，你需要把當(dāng)前的工作目錄切換到JsDoc Toolkit目錄，并確保將java.exe所在目錄添加到環(huán)境變量中。
java -jar jsrun.jar app\run.js -a -t=templates\jsdoc mycode.js
mycode.js是需要生成文檔的js代碼，如果mycode.js和JsDoc不在同一目錄，請加上文件的絕對或者相對路徑。如果項目中有多個js， 可以使用通配符*來指定多個js文件(*.js)。-e參數(shù)指定文檔編碼，-t參數(shù)指定文檔模板位置（可以新建或修改模板文件讓輸出的代碼文件更具特 色），生成的文檔文件在JsDoc目錄下的out目錄中。為了使用方便，我寫了一個批處理文件，你可以將代碼保存為run.bat，放到JsDoc目錄 下：
::run.bat
@echo off
::js文件名(換成你的js文件名)
set jsname=jquery.js
::js文件路徑(換成你的js文件路徑)
set jspath=C:\test\
echo start...
java -jar jsrun.jar app\run.js -a -e=GBK -t=templates\jsdoc "%jspath%%jsname%.js"
::out\%jsname%\index.html
echo finished.
pause
常用關(guān)鍵字
| author |
標(biāo)識代碼作者 |
| class |
標(biāo)識該函數(shù)是一個類的構(gòu)造函數(shù) |
| constant |
聲明常量 |
| constructor |
同class |
| default |
默認(rèn)值 |
| deprecated |
聲明已棄用的對象 |
| description |
對象描述 |
| event |
事件函數(shù) |
| example |
例子代碼 |
| fileOverview |
Javascript文件總體描述 |
| ignore |
忽略有這個標(biāo)記的函數(shù) |
| link |
與其他JsDoc對象關(guān)聯(lián) |
| name |
顯示聲明JsDoc不能自動檢測的對象 |
| namespace |
聲明命名空間 |
| param |
參數(shù) |
| private |
聲明私有對象 |
| property |
顯式聲明一個屬性 |
| public |
聲明公開對象 |
| requires |
聲明所依賴的對象或文件 |
| returns |
返回值 |
| see |
聲明可參考的其它對象 |
| since |
聲明對象從指定版本開始生效 |
| static |
顯式聲明一個靜態(tài)對象 |
| throws |
聲明函數(shù)執(zhí)行過程中可能拋出的異常 |
| type |
聲明變量類型或者函數(shù)返回值類型 |
| version |
版本號 |
詳細(xì)語法請參閱：JsDoc Toolkit Wiki
整理自：http://blog.tugai.net/2010/01/08/jsdoc-toolkit-usage/