sublime text 3 插件 DocBlockr 与 JavaScript 注释规范
1、引子
在写代码的时候,尤其是写脚本,最需要注释了。目前脚本、样式的注释格式都有一个已经成文的约定规范(这些约定规范最初是 YUI Compressor 制定的,详见参考资料)了,如下:
/**
* 这里的注释内容【会】被压缩工具压缩
*/
/*!
* 这里的注释内容【不会】被压缩工具压缩
* 与上面一个注释块不同的是,第2个*换成了!
*/
其中说到这里说到的压缩工具有 YUI Compressor 、Google Closure Compiler、gulp-uglify、grunt-contrib-uglify 等,这些压缩工具都支持以上的压缩约定。常常把文件的关键信息放在第 2 种注释内容里,如文件名称、版本号、作者等。
关于这些关键信息,都有一些关键词和一定的格式来书写。关键词书写格式为:
/**
* @author ydr.me
* @version 1.0
*/
使用 @key desc
格式来书写,常用的关键词有:
关键词 | 描述 |
---|---|
@auhor | 作者 |
@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/
如果你对这篇内容有疑问,欢迎到本站社区发帖提问 参与讨论,获取更多帮助,或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱,如果其他用户或者作者回复了您的评论,将不能在第一时间通知您!
发布评论