1、引子

在寫代碼的時候，尤其是寫腳本，最需要注釋了。目前腳本、樣式的注釋格式都有一個已經成文的約定規范（這些約定規范最初是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. */

2、插件

使用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、並且在注釋塊中，按@鍵可以展開關鍵詞：

 

 

3、參考資料

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