一、引子

在寫代碼的時候，尤爲是寫腳本，最須要註釋了。javascript

DocBlockr is a package for Sublime Text 2 & 3 which makes writing documentation a breeze. DocBlockr supports JavaScript (including ES6), PHP, ActionScript, Haxe, CoffeeScript, TypeScript, Java, Apex, Groovy, Objective C, C, C++ and Rust.html

目前腳本、樣式的註釋格式都有一個已經成文的約定規範（這些約定規範最初是YUI Compressor制定的，詳見參考資料）了，以下：java

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

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

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

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

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

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

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

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

二、插件

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

A、先寫完你的函數curl

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

B、而後在函數的前面一行，輸入sublime-text-3

  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) {
  9. }

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

 

\

 

Basic variable substitution is supported here for the variables date and datetime, wrapped in double curly brackets.

// jsdocs_extra_tags = ['@date {{date}}', '@anotherdate {{datetime}}']
/**<<enter>>
function foo() {}

/**
 * [foo description]
 * @date     2013-03-25
 * @datetime 2013-03-25T21:16:25+0100
 * @return   {[type]}
 */

默認的補全代碼卻沒有做者，時間等信息，解決方法，參考逛網，打開Sublime,並安裝DocBlockr插件
打開Preferences -> Package Settings -> DocBlockr->Settings - User 並新建一個User配置文件,也能夠直接將配置文件保存到"Default Settins"
將下面的代碼保存到新建的User配置文件中.,若是是保存在「Default Settins」裏則須要將覆蓋默認的配置(不建議在默認的配置中進行更改)

{
    "jsdocs_extra_tags":["@Author Author","@DateTime {{datetime}}"]
}

 
 
 
 
三、參考資料
 
 
     
  
  • YUI Compressor註釋規範：http://yui.github.io/yuidoc/syntax/
    •  
  
  • JSDOC：http://usejsdoc.org/
    •  
  
  • https://packagecontrol.io/packages/DocBlockr
    •