DIV CSS 佈局教程網

JSDoc 標註規範詳解:用註釋自動生成 JavaScript API 文件
編輯:關於JavaScript     

寫 JavaScript 時,如果只靠人肉整理文件,專案一大就會失控。JSDoc 的解法很直覺:讓註釋本身成為文件的來源。它會掃描原始碼中的區塊註釋,抽出類別、方法、成員與參數資訊,最後產出一份和程式碼同步的 API 說明頁面,概念上等同於 Java 世界裡的 Javadoc。

工具版本與取得方式

JSDoc Toolkit 曾推出 2.3.2 版本,內容以修正前版的問題為主。若你的建置流程使用 Ant,官方另有對應的 Ant 任務(JsDoc Toolkit Ant Task)可以直接掛上去。專案首頁為 https://www.jsdoctoolkit.org/,壓縮檔可從 Google Code 下載。

常用標註一覽

下表整理最常使用到的標籤,含括函式、類別、可見性與文件結構等面向:

  • @param / @argument:描述函式的參數名稱與用途。
  • @returns:說明函式的回傳值。
  • @author:標示程式碼作者。
  • @deprecated:宣告該函式已不建議使用,未來版本可能整段移除。
  • @see:建立一個指向指定類別說明的 HTML 連結。
  • @version:指定發布版本。
  • @requires:建立指向此類別所依賴類別的連結。
  • @throws / @exception:描述函式可能拋出的例外型別。
  • {@link}:與 @see 類似,但可以直接嵌在註釋文字內部。
  • @fileoverview:特殊標記。若放在檔案的第一個文件區塊中,該區塊其餘內容會被當成整個檔案的概述。
  • @class:提供類別資訊,用於建構子的文件。
  • @constructor:明確指出某函式是類別的建構子。
  • @type:指定函式的回傳型別。
  • @extends:指示某類別繼承自另一類別。JSDoc 通常能自行推斷,但部分情況仍需手動標註。
  • @private:宣告私有成員。私有項目預設不會出現在文件中,除非執行時加上 --private 參數。
  • @final:指示該值為常數。要注意 JavaScript 本身並無法真正保證不可變。
  • @ignore:要求 JSDoc 略過帶有此標記的函式。

命令列操作方式

解壓縮後先看 README.txt,裡面已有完整說明。產生文件需要透過命令列執行,基本語法如下:

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

如果每次都要打這串指令太麻煩,可以把內容存成一個 .bat 檔,之後雙擊執行即可。

參數說明

  • -a:包含所有方法,即使沒有註釋也會輸出。
  • -e:指定讀寫檔案的編碼,預設為 UTF-8;中文環境常用 GB18030。
  • -t:指定輸出文件的樣板模板。
  • test/*.js:代表 test 目錄底下所有 JavaScript 檔。

執行完畢後,結果預設輸出到 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。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved