1. 生成API文檔的步驟：

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

簡單舉例：

/**
* 翻轉一個字符串
*
* @param  {String} 輸入需要翻轉的字符串
* @return {String} 翻轉后的字符串
**/

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

YUIDoc范例：

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

app.js:

/**
* 我的javascript應用程序
*
* @module myapp
*/

//使用命名空間來定義一個空對象
var MYAPP = {};

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

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

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

@class：這里有些命名不當，他實際意思是指對象或者構造函數(shù)

@method：定義對象中的方法和方法名

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

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

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

@property和@type描述了對象的屬性。

2. 編寫API目的：

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