近來前端組小盆友開發的類庫越來越多，很多情況下彼此不知道寫了些什么方法，為了更好的合作提高工作效率，找了個比較好的api文檔生成方法。使用jsdoc-toolkit來自動生成js api文檔。
一、 環境搭建
1) 首先要安裝java環境，如果不太了解的參看：http://jingyan.baidu.com/article/e75aca85b29c3b142edac6a8.html
2) 安裝jsdoc-toolkit
下載地址：http://code.google.com/p/jsdoc-toolkit/downloads/list
解壓下載的壓縮包（可以隨便指定目錄），並進入該目錄，shift+鼠標右擊，在菜單中選擇打開cmd命令：敲入如下命令：
java -jar jsrun.jar app/run.js
如果出現：
WARNING: No source files to work on. Nothing to do.
就代表一切安裝成功了。
由於本文着重寫如何生成js api，所以有關jdk安裝就不多述了。
二、 准備符合規范的注釋代碼文件
1) 符合規定的注釋
用sublime的小盆友，安裝下sublime插件DocBlockr。其他編輯器有沒有輔助插件我就不知道了，就以此來說明下注釋規范。
安裝成功后，在寫好的函數上一行敲入/**然后回車，就會出現：
/** * [__ description] * @param {[type]} key [description] * @return {[type]} [description] */
以上就是符合api規范的注釋，三行分別為函數描述，參數及返回值。
寫好的注釋如：
/** * 翻譯函數 * @param {String} key 參數字符串 * @return {String} 返回字符串 * @example __('test') */
特別列出常用注釋命令參數：
命令名 描述
@param
@argument 指定參數名和說明來描述一個函數參數。
@return
@example 函數使用示例
@returns 描述函數的返回值。
@author 指示代碼的作者。
@deprecated 指示一個函數已經廢棄，不建議使用，而且在將來版本的代碼中可能會徹底刪除。要避免使用這段代碼。
@see 創建一個HTML鏈接指向指定類的描述。
@version 指定發布版本。
@requires 創建一個HTML鏈接，指向這個類所需的指定類。
@throws
@exception 描述函數可能拋出的異常的類型。
@link 創建一個HTML鏈接，指向指定的類。這與@see很類似，但@link能嵌在注釋文本中。 @author 指示代碼的作者。（譯者注：這個標記前面已經出現過，建議去掉）
@fileoverview 這是一個特殊的標記，如果在文件的第一個文檔塊中使用這個標記，則指定該文檔塊的余下部分將用來提供文件的一個概述。
@class 提供類的有關信息，用在構造函數的文檔中。
@constructor 明確一個函數是某個類的構造函數。
@type 指定函數的返回類型。
@extends 指示一個類派生了另一個類。通常JSDoc自己就可以檢測出這種信息，不過，在某些情況下則必須使用這個標記。
@private 指示一個類或函數是私有的。私有類和函數不會出現在HTML文檔中，除非運行JSDoc時提供了---private命令行選項。
@final 指示一個值是常量值。要記住JavaScript無法真正保證一個值是常量。
@ignore JSDoc 會忽略有這個標記的函數。
2) 符合規定的代碼
命名空間規范
示例代碼test1.js
/** * @namespace 通用工具函數. */ Utils = { /** * 翻譯函數 * @param {String} str 參數字符串 * @return {String} 返回字符串 */ helloApi: function(str) { return str; }
}
Utils上的namespace說明一定要加，指定該命名空間。
helloApi就是Utils的靜態函數。
修改一下，utils前加var：
/** * @namespace 通用工具函數. */ var Utils = { /** * 翻譯函數 * @param {String} str 參數字符串 * @return {String} 返回字符串 */
helloApi: function(str) { return str; }
}
加了var之后效果和上面一段代碼一樣， 因為Utils都是全局變量。生成的都是Utils下的靜態函數說明。
如果使用閉包：
define(function(require){ /** * @namespace 通用工具函數. */ var Utils = { /** * 翻譯函數 * @param {String} str 參數字符串 * @return {String} 返回字符串 */
helloApi: function(str) { return str; }
} return Utils; })
將不能生成代碼，因為Utils變為閉包內的變量，所以jsdoc不能找到公開命名空間。
目前我能想到的方法就是在生成doc時臨時將var去掉，之后再加上，有點麻煩，不知道各位有沒有更好的方式。
生成工具類靜態函數及類函數
上面在講命名空間的時候是以靜態類為例的，於是這里就講一下如何生成類方法。
define(function(require){ /** * @namespace 通用工具函數. */ Utils = function() {}; Utils.prototype = { /** * 翻譯函數 * @param {String} str 參數字符串 * @return {String} 返回字符串 */
helloApi: function(str) { return str; }
} return Utils; })
這樣就生成了一個utils類，__為他的方法。中途不能有參數傳遞，如：
define(function(require){ /** * @namespace 通用工具函數. */ Utils = function() {}; var fn = Utils.prototype; fn = { /** * 翻譯函數 * @param {String} str 參數字符串 * @return {String} 返回字符串 */
helloApi: function(str) { return str; }
} return Utils; })
三、使用jsdoc生成文檔
1) 生成test1.js的文檔
將test1.js文件放入jsdoc目錄下的app文件夾中：
然后敲入命令：
java -jar jsrun.jar app/run.js -a -t=templates/jsdoc app/test1.js
如果成功的話，你就會看到當前文件夾里多出了一個叫做 out 的文件夾，生成的文檔就在里面了！然后你就可以在瀏覽器中查看了。
java -jar jsrun.jar app/run.js -a -t=templates/jsdoc app/test1.js
如果寫成：
java -jar jsrun.jar app/run.js -a -t=templates/jsdoc app
將生成app文件夾下所有文件的api文檔。
如果想了解所有命令參數，通過-help可以查看
java -jar jsrun.jar app/run.js --help
簡單介紹幾個：
-a 或者 --allfunctions ：為全部函數生成文檔，包括那些沒有寫注釋的。
-c 或者 --conf ：使用配置文件
-d= 或者 --directory=：指定生成文檔的輸出目錄，默認是 “out”
-e= 或者 --encoding=：指定編碼方式
-n 或者 --nocode ：忽略所有代碼，只為有 @name 標簽的注釋生成文檔。
-o= 或者 --out= ： 將日志信息輸出到指定文件
-q 或者 --quiet ： 不輸出任何信息，包括警告。
-t= 或者 --template= ：指定文檔的模板，這個參數必須提供。
2) 使用配置文件
為了更方便的生成文檔，一定需要使用配置文件來指定各項參數，包括指定輸入輸出目錄。下面講一下如何使用配置文件。
在jsdoc目錄下的conf文件夾中有個sample.conf文件。按注釋修改目錄。
/* This is an example of one way you could set up a configuration file to more conveniently define some commandline options. You might like to do this if you frequently reuse the same options. Note that you don't need to define every option in this file, you can combine a configuration file with additional options on the commandline if your wish. You would include this configuration file by running JsDoc Toolkit like so: java -jar jsrun.jar app/run.js -c=conf/sample.conf */ { // source files to use源文件路徑 // 如修改為['app'],將分析app下所有文件，注意一定要寫成反斜杠'/'，如果是'\'不能分析路徑。 _: ['app/test1.js'], // document all functions, even uncommented ones a: true, // including those marked @private p: true, // some extra variables I want to include D: {generatedBy: "Michael Mathews", copyright: "2008"}, // use this directory as the output directory d: "docs", // use this template t: "templates/jsdoc" }
然后在cmd中輸入：
java -jar jsrun.jar app/run.js -c=conf/test.conf
便可以方便的生成文檔，隨時改變conf內容而不用在cmd中改變命令。
參考：http://www.oschina.net/question/12_7615
如果有不對的地方，大家請拍磚。