DocBlockr

DocBlockr是 sublime的插件包,目前支持 Sublime Text 2 & 3。 DocBlockr 支持 Javascript, PHP, ActionScript, CoffeeScript, Java, Groovy, Objective C, C and C++.的注释的快速生成。

安装

使用 Package Control 安装 DocBlockr插件:

  • 在 Package Control 中选择 Install package 或者按 Ctrl+Shift+P,
    打开命令板
  • 输入 pci 然后选择 Install Package
    搜索输入 DocBlockr 找到 DocBlockr,
  • 点击就可以自动完成安装。

使用

在新的一行中输入 /** 后按下 enter 或者 tab

Doc​Blockr - 图1

一个星号的注释使用方法

Doc​Blockr - 图2

为一个函数添加注释,函数的名称和参数,在函数前输入 /** 后回车,他会自动解析并自动添加注释。

Doc​Blockr - 图3

在生成注释后, 按 tab 快速切换需要修改的地方

Doc​Blockr - 图4

他还提供了对其他语言的支持

Doc​Blockr - 图5

DocBlockr 会尝试的去猜测 function 的返回值

  • 如果方法名中以 “set” 或 “add” 开头,它将不会为注释插入 @return. 如: function setName() {...}
  • 如果方法名中以 “is” 或 “has” 开头,它将为注释 @return 设置为 Boolean. 如: @return {Boolean}
  • 在Javascript中,如果函数以一个大写字母开始,并假定函数定义为一个类,此时不添加@return标记。

变量的文档

如果在新的一行声明一个变量,在 /** 后 按下 shift+enter , DocBlocker 将试着猜测变量的数据类型,并插入响应类型注释。

Doc​Blockr - 图6

DocBlocker 除了视图判断以 is 或 has 这些开头命名的参数为 booleans 类型为,还将 callback, cb, done, fn, 和 next 判断成 Function 类型。例子如下:

  1. /**
  2. * [isMe description]
  3. *
  4. * @method isMe
  5. *
  6. * @param {Boolean} isA [description]
  7. * @param {[type]} isb [description]
  8. * @param {Function} callback [description]
  9. * @param {Function} cb [description]
  10. * @param {Function} done [description]
  11. * @param {Function} fn [description]
  12. * @param {Function} next [description]
  13. *
  14. * @return {Boolean} [description]
  15. */
  16. function isMe(isA, isb, callback, cb, done, fn, next){
  17. return a;
  18. }

用户还可以通过自定义规则完成预判断。比如下面的的例子中设定了 b 开头的参数是 bool 类型。这些设定可以通过修改 Base File.sublime-settings 文件中的 jsdocs_notation_map属性

  1. {
  2. "jsdocs_notation_map": [
  3. {
  4. "prefix": "b", // a prefix, matches only if followed by an underscore or A-Z
  5. "type": "bool" // translates to "Boolean" in javascript, "bool" in PHP
  6. },
  7. {
  8. "regex": "tbl_?[Rr]ow", // any arbitrary regex to test against the variable name
  9. "type": "TableRow" // you can add your own types
  10. }
  11. ]
  12. }

下面我们来添加一个私有方法猜测的配置,这个配置意思是以 _ 开头命名的方法都被预判为私有方法,在生成注释时会在注释文档中添加 @private

  1. {
  2. "jsdocs_notation_map": [
  3. {
  4. "prefix": "_",
  5. "tags": ["@private"]
  6. }
  7. ]
  8. }

注释其他说明

在docblock文档流内按下回车,文档会自动加*

Doc​Blockr - 图7
Doc​Blockr - 图8

使用 // 后换行, docbolck 会在新的一行自动加上 //

Doc​Blockr - 图9

如果你想终止智能提速,你可以通过按下 shift+enter 去停止自动预测。

有时候我们的参数说明可能很长,我们可以在换行后按下 tab 实现快速缩进。

Doc​Blockr - 图10

修饰类注释

有时候你会修以下类型的修饰类注释

  1. /////////////////
  2. // Foo bar baz //
  3. /////////////////

你可以通过输入 // Foo bar baz 后按下<<Ctrl+Enter>> 来快速实现。

添加额外的标签

可以在docblock中输入 @ 获得JSDoc, Google Closure Compiler, YUIDocPHPDoc.的全部支持的列表。

配置

你可以通过 Preferences -> Package Settings -> DocBlockr -> settings default 进入 Base File.sublime-settings 文件中修改相应配置。

具体的进入文件就可以看到举例