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, YUIDoc ， PHPDoc.的全部支持的列表。

配置

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

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