Sublime Text3 插件：DocBlockr与javascript注释规范

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

1、引子

在写代码的时候，尤其是写脚本，最需要注释了。目前脚本、样式的注释格式都有一个已经成文的约定规范（这些约定规范最初是YUI Compressor制定的，详见参考资料）了，如下：

1. /**
2. * 这里的注释内容【会】被压缩工具压缩
3. */
4. /*！
5. * 这里的注释内容【不会】被压缩工具压缩
6. * 与上面一个注释块不同的是，第2个*换成了!
7. */

其中说到这里说到的压缩工具有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){
2. }

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

D、并且在注释块中，按@键可以展开关键词：

3、参考资料

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