一、引子

在写代码的时候，尤为是写脚本，最须要注释了。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
    •