寫 JavaScript 時,如果只靠人肉整理文件,專案一大就會失控。JSDoc 的解法很直覺:讓註釋本身成為文件的來源。它會掃描原始碼中的區塊註釋,抽出類別、方法、成員與參數資訊,最後產出一份和程式碼同步的 API 說明頁面,概念上等同於 Java 世界裡的 Javadoc。
JSDoc Toolkit 曾推出 2.3.2 版本,內容以修正前版的問題為主。若你的建置流程使用 Ant,官方另有對應的 Ant 任務(JsDoc Toolkit Ant Task)可以直接掛上去。專案首頁為 https://www.jsdoctoolkit.org/,壓縮檔可從 Google Code 下載。
下表整理最常使用到的標籤,含括函式、類別、可見性與文件結構等面向:
解壓縮後先看 README.txt,裡面已有完整說明。產生文件需要透過命令列執行,基本語法如下:
java -jar jsrun.jar app/run.js -a -e=GB18030 -t=templates/jsdoc test/*.js
如果每次都要打這串指令太麻煩,可以把內容存成一個 .bat 檔,之後雙擊執行即可。
執行完畢後,結果預設輸出到 out/jsdoc 目錄,該路徑同樣可以自訂。若想查看完整參數,可執行:
java -jar jsrun.jar app/run.js --help
輸出內容大致包含:-a/--allfunctions、-c/--conf(載入設定檔)、-d=<PATH>/--directory(輸出目錄,預設 out)、-D/--define(定義變數,於程式中以 JSDOC.opt.D.myVar 取得)、-e/--encoding、-E/--exclude(以正則表達式排除檔案)、-h/--help、-n/--nocode(忽略程式碼,只處理帶 @name 的註釋)、-o/--out(將日誌導向檔案)、-p/--private、-q/--quiet 等選項。
/**
* @fileOverview 簡單的方法標註示例
* @author <a href="llying.javaeye.com">llying</a>
* @version 0.1
*/
/**
* @description 加法運算
* @param {Num} num1 加數
* @param {Num} num2 被加數
* @return {Num} result 結果
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* @description 減法運算
* @param {Num} num1 減數
* @param {Num} num2 被減數
* @return {Num} result 結果
*/
function minus(num1, num2) {
return num1 - num2;
}
/**
* @fileOverview 簡單的類別物件標註示例
* @author <a href="llying.javaeye.com">llying</a>
* @version 0.1
*/
/**
* @author llying
* @constructor Person
* @description 一個 Person 類別
* @see The <a href="#">llying</a>.
* @example new Person("張三", 15);
* @since version 0.1
* @param {String} username 姓名
* @param {Num} age 年齡
*/
function Person(username, age) {
/**
* @description {String} 姓名
* @field
*/
this.username = username;
/**
* @description {Num} 年齡
* @field
*/
this.age = age;
/**
* @description 彈出 say 內容
* @param {String} content 內容
*/
this.say = function (content) {
alert(this.username + " say :" + content);
};
/**
* @description 回傳 JSON 格式的字串
* @return {String} JSON 格式
* @see Person#say
*/
this.getJson = function () {
return "{name:" + this.username + ",age:" + this.age + "}";
};
}
把上述檔案放進 test 目錄,重新執行一次產生文件的指令,一組可讀性良好的 API 頁面就完成了,從此不必再羨慕 Java 開發者的 Javadoc。
本文只列出最實用的標籤,更完整的清單可參考官方文件:Tag Reference。