Sublime Text3 插件：DocBlockr與javascript註釋規範

原：http://www.ithao123.cn/content-719950.html

一、引子

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

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

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

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

1. /**
2. * @author ydr.me
3. * @version 1.0
4. */

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

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

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

1. /**
2. * @param {String} 參數描述
3. */

二、插件

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

A、先寫完你的函數

1. function testFunction(a, b, c){
3. }

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

1. /**

C、而後回車，自動生成

1. /**
2. * [testFunction description]
3. * @param {[type]} a [description]
4. * @param {[type]} b [description]
5. * @param {[type]} c [description]
6. * @return {[type]} [description]
7. */
8. function testFunction(a, b, c){
10. }

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

 

 

三、參考資料

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