使用jsdoc-toolkit來自動生成js api文檔

近來前端組小盆友開發的類庫愈來愈多，不少狀況下彼此不知道寫了些什麼方法，爲了更好的合做提升工做效率，找了個比較好的api文檔生成方法。使用jsdoc-toolkit來自動生成js api文檔。

1、 環境搭建

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安裝就很少述了。

2、 準備符合規範的註釋代碼文件

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;
})

3、使用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

若是有不對的地方，你們請拍磚。