Sublime Text3 插件:DocBlockr与javascript注释规范
原:http://www.ithao123.cn/content-719950.html
1、引子
在写代码的时候,尤其是写脚本,最需要注释了。目前脚本、样式的注释格式都有一个已经成文的约定规范(这些约定规范最初是YUI Compressor制定的,详见参考资料)了,如下:
- /**
- * 这里的注释内容【会】被压缩工具压缩
- */
- /*!
- * 这里的注释内容【不会】被压缩工具压缩
- * 与上面一个注释块不同的是,第2个*换成了!
- */
其中说到这里说到的压缩工具有YUI Compressor 、Google Closure Compiler、gulp-uglify、grunt-contrib-uglify等,这些压缩工具都支持以上的压缩约定。常常把文件的关键信息放在第2种注释内容里,如文件名称、版本号、作者等。
关于这些关键信息,都有一些关键词和一定的格式来书写。关键词书写格式为:
- /**
- * @author ydr.me
- * @version 1.0
- */
使用@key desc
格式来书写,常用的关键词有:
关键词 | 描述 |
---|---|
@author |
作者 |
@param |
参数 |
@example |
例子 |
@link |
链接 |
@namespace |
命名空间 |
@requires |
依赖 |
@return |
返回值 |
@version |
版本号 |
其中,param关键词的格式为:
- /**
- * @param {String} 参数描述
- */
2、插件
使用package control安装DocBlockr。安装完成后使用方法如下:
A、先写完你的函数
- function testFunction(a, b, c){
- }
B、然后在函数的前面一行,输入
- /**
C、然后回车,自动生成
- /**
- * [testFunction description]
- * @param {[type]} a [description]
- * @param {[type]} b [description]
- * @param {[type]} c [description]
- * @return {[type]} [description]
- */
- function testFunction(a, b, c){
- }
D、并且在注释块中,按@
键可以展开关键词:
3、参考资料
- YUI Compressor注释规范:http://yui.github.io/yuidoc/syntax/
- JSDOC:http://usejsdoc.org/