JsDoc Toolkit：JavaScript 文檔利器

隨著 Web2.0 的風靡，JavaScript 已經成為一門被人們重新認識的程式設計語言，由於大量 JS 開源架構的出現，利用 JavaScript 開發 的項目越來越多，越來越大。同時，也有越來越多JavaScript 開發問題暴露出來，如效能、網頁載入速度等，其中，JavaScript 文檔維護也成 為了開發人員亟待解決的一個難題。

許多現代程式設計語言都有自己的整合化文檔產生工具，像 Java 有 JavaDoc，.NET有 NDoc，PHP有 PHPDoc，這些自動化文檔工具可以根據代碼中的注釋自動產生代碼文檔。

JsDoc Toolkit 就是這樣一個自動化文檔工具，它是發布在 Google code 上的一個開源項目，和其他語言的文檔工具一樣，它可以自動從 JavaScript 代碼中提取注釋產生格式化文檔。 

http://code.google.com/p/jsdoc-toolkit/downloads/list

運行環境

JsDoc Toolkit是用Java開發的，運行時需要 Java 1.5+。

用法

在運行之前，你需要把當前的工作目錄切換到JsDoc Toolkit目錄，並確保將java.exe所在目錄添加到環境變數中。

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

mycode.js是需要產生文檔的js代碼，如果mycode.js和JsDoc不在同一目錄，請加上檔案的絕對或者相對路徑。如果項目中有多個js， 可以使用萬用字元*來指定多個js檔案(*.js)。-e參數指定文檔編碼，-t參數指定文件範本位置（可以建立或修改模板檔案讓輸出的代碼檔案更具特 色），產生的文檔檔案在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.htmlecho finished.

pause

常用關鍵字

author	標識代碼作者
class	標識該函數是一個類的建構函式
constant	聲明常量
constructor	同class
default	預設值
deprecated	聲明已棄用的對象
description	對象描述
event	事件函數
example	例子代碼
fileOverview	Javascript檔案總體描述
ignore	忽略有這個標記的函數
link	與其他JsDoc對象關聯
name	顯示聲明JsDoc不能自動檢測的對象
namespace	聲明命名空間
param	參數
private	聲明私人對象
property	顯式聲明一個屬性
public	聲明公開對象
requires	聲明所依賴的對象或檔案
returns	傳回值
see	聲明可參考的其它對象
since	聲明對象從指定版本開始生效
static	顯式聲明一個靜態對象
throws	聲明函數執行過程中可能拋出的異常
type	聲明變數類型或者函數傳回值類型
version	版本號碼

詳細文法請參閱：JsDoc Toolkit Wiki

整理自：http://blog.tugai.net/2010/01/08/jsdoc-toolkit-usage/

本文是使用 B3log Solo 從 簡約設計の藝術 進行同步發布的原文地址：http://88250.b3log.org/articles/2010/11/26/jsdoc-toolkit-usage.html