JavaScript註釋規範

一、引子

在寫代碼的時候，尤爲是寫腳本，最須要註釋了。目前腳本、樣式的註釋格式都有一個已經成文的約定規範（這些約定規範最初是YUI Compressor制定的，詳見參考資料）了，以下：

/**
 * 這裏的註釋內容【會】被壓縮工具壓縮
 */

/*！
 * 這裏的註釋內容【不會】被壓縮工具壓縮
 * 與上面一個註釋塊不一樣的是，第2個*換成了!
 */

其中說到這裏說到的壓縮工具備YUI Compressor 、Google Closure Compiler、gulp-uglify、grunt-contrib-uglify等，這些壓縮工具都支持以上的壓縮約定。經常把文件的關鍵信息放在第2種註釋內容裏，如文件名稱、版本號、做者等。

關於這些關鍵信息，都有一些關鍵詞和必定的格式來書寫。關鍵詞書寫格式爲：

/**
 * @author ydr.me
 * @version 1.0
 */

使用@key desc格式來書寫，經常使用的關鍵詞有：

關鍵詞	描述
@auhor	做者
@param	參數
@example	示例
@link	連接
@namespace	命名空間
@requires	依賴模塊
@return	返回值
@version	版本號

其中，param關鍵詞的格式爲：

/**
 * @param {String} 參數描述
 */

二、插件

使用package control安裝DocBlockr。安裝完成後使用方法以下：

A、先寫完你的函數

function testFunction(a, b, c) {

}

B、而後在函數的前面一行，輸入

/**

C、而後回車，自動生成

/**
 * [testFunction description]
 * @param  {[type]} a [description]
 * @param  {[type]} b [description]
 * @param  {[type]} c [description]
 * @return {[type]}   [description]
 */
function testFunction(a, b, c) {

}

D、而且在註釋塊中，按@鍵能夠展開關鍵詞：

三、參考資料

• YUI Compressor註釋規範：http://yui.github.io/yuidoc/syntax/
• JSDOC：http://usejsdoc.org/