六、JS 編寫API文檔

1. 生成API文檔的步驟：

• 編寫特殊格式的代碼塊（即一些注釋塊）
• 運(yùn)行工具來解析代碼和注釋（工具如：JSDoc Toolkit和YUIDoc）
• 發(fā)布工具解析的結(jié)果，大多數(shù)情況是采用HTML格式發(fā)布（如網(wǎng)頁版的API文檔就是利用工具生成的）

簡(jiǎn)單舉例：

/**
* 翻轉(zhuǎn)一個(gè)字符串
*
* @param  {String} 輸入需要翻轉(zhuǎn)的字符串
* @return {String} 翻轉(zhuǎn)后的字符串
**/

var reverse = function (input) {
    //...
    return output;
};

YUIDoc范例：

完整范例：本程序由一個(gè)文件(app.js)組成，該文件僅有一個(gè)模塊(myapp)。

app.js:

/**
* 我的javascript應(yīng)用程序
*
* @module myapp
*/

//使用命名空間來定義一個(gè)空對(duì)象
var MYAPP = {};

//定義一個(gè)包含兩個(gè)方法(sum()和multi())的math_stuff對(duì)象
/**
* @namespace MYAPP
* class math_stuff
*/

MYAPP.math_stuff = {
    /**
    * Sums two numbers
    *
    * @method sum
    * param     {Number}    是第一個(gè)數(shù)
    * param     {Number}    是第二個(gè)數(shù)
    * return    {Number}    兩個(gè)輸入的總和
    */
    sum: function (a, b) {
        return a + b;
    },
    /**
    * Multiplies two numbers
    * param     {Number}    是第一個(gè)數(shù)
    * param     {Number}    是第二個(gè)數(shù)
    * return    {Number}    兩個(gè)輸入相乘后結(jié)果
    */
    multi: function (a, b) {
        return a * b;
    }
};

@namespace：這里用于命名包含以上對(duì)象的全局引用的名稱

@class：這里有些命名不當(dāng)，他實(shí)際意思是指對(duì)象或者構(gòu)造函數(shù)

@method：定義對(duì)象中的方法和方法名

@param：列舉函數(shù)所使用的參數(shù)。其中將參數(shù)類型用大括號(hào)括起來，并在其后注釋參數(shù)名及描述。

@return：類似于@param，這里用于描述返回值的，并且該方法沒有名稱。

@constructor：表明這個(gè)“類”實(shí)際上是一個(gè)構(gòu)造函數(shù)

@property和@type描述了對(duì)象的屬性。

2. 編寫API目的：

• 為API編寫注釋不僅僅是一中提供參考文檔的簡(jiǎn)便方法，而且還有其他用途——通過再次審查代碼，提高代碼質(zhì)量。
• 在解決問題時(shí)寫出的解決方案僅僅是一個(gè)初稿。該解決方案可以給出令人期待的輸出，但是該方案是否是最佳方案呢？改代碼是否可讀、易于理解、維護(hù)和升級(jí)呢？當(dāng)您再次審視代碼時(shí)您將更加確定代碼哪些部分可以改進(jìn)——如何使得代碼更容易繼續(xù)更新，移除一些不足之處等。它可以極大地幫助您創(chuàng)建高質(zhì)量的代碼。