DocBlockr

DocBlockr是一个为Sublime Text 2 & 3设计的软件包，它让编写文档变得轻而易举。DocBlockr支持以下编程语言：JavaScript (包括ES6), PHP, ActionScript, Haxe, CoffeeScript, TypeScript, Java, Apex, Groovy, Objective C, C, C++ 和 Rust。

安装

包管理器

1. 打开包管理器: 首选项 -> 包管理器
2. 选择包管理器: 安装包
3. 在搜索框中输入DocBlockr并选择安装该软件包

功能请求 & 缺陷报告

您可以将这些内容留在此处。我们热烈欢迎pull请求，但在开始之前请先阅读CONTRIBUTING.md！基本上：在这个仓库中，主要开发分支是develop，而稳定的“production”分支是master。请记住，从develop分支创建分支并将pull请求发送回该分支。

表达您的喜爱

变更日志

• v2.14.1, 2015年8月17日
  • 修复了reparsing doc block时缩进错误
• v2.14.0, 2015年6月15日
  • 添加了jsdocs_function_description选项（感谢Gerard Roche）
  • 更有效地处理了解析错误（感谢Gerard Roche）
• v2.13.3, 2015年6月4日
  • PHP数组缩写现在可以正确识别（感谢Gerard Roche）
  • 使用制表符缩进时装饰注释的效果更好（感谢Jack Cherng）
• v2.13.2, 2015年3月30日
  • 更新了PHPDoc自动完成以与新的规范保持一致（感谢Gerard Roche）
  • 正确处理Java中类型名称内部出现逗号的情况
  • 在首选项菜单中添加了README链接
• 2.13.1，2015年3月29日
  • 添加了对Apex语言的支持（感谢@michacom）
  • 修复C/C++中识别多维数组的问题
  • 修复Java中重新格式化和重新解析docblocks的问题
  • 添加了可禁用的选项
  • 禁用空格中打开内联docblocks（jsdocs_quick_open_inline）
  • 内联注释装饰（jsdocs_decorate）

更早的历史可以在历史文件中找到。

用法

以下是一些关于包所能做什么的示例。注意，不需要键盘快捷键来触发这些完成操作——只需正常输入即可！

Docblock完成

在/**（或Coffee-Script的###*）后按enter或tab，将产生一个新行并关闭注释。

单星号注释块的行为类似

函数文档

然而，如果紧跟在函数定义之后的行包含一个函数定义，其名称和参数将被解析，并自动添加一些文档。

按Tab键可以在字段间前进，按Shift+Tab键可以在字段间后退。

如果有很多参数或很长的变量名，则有时将参数分散到多行很有用。DocBlockr也处理这种情况

在支持类型提示或默认值的语言中，则这些类型将被预先填充为数据类型。

DocBlockr将尝试智能猜测函数的返回值。

• 如果函数名称是或以“set”或“add”开头，则不会插入@return。
• 如果函数名称是或以“is”或“has”开头，则假定它返回一个Boolean。
• 在JavaScript中，如果函数以大写字母开头，则假定它是一个类定义。不会添加@return标签。
• 在PHP中，一些魔术方法的值被预先填充
  • __construct、__destruct、__set、__unset、__wakeup没有@return标签。
  • __sleep返回一个array。
  • __toString返回一个string。
  • __isset返回一个bool。
• 在ES6 JavaScript中，生成器函数获得一个@yield标签而不是@return

变量文档

如果随后的行包含一个变量声明，DocBlockr将尝试确定变量的数据类型并将它插入到注释中。

在/**开头后按space或shift+enter键可以插入内联docblock。

DocBlockr也将尝试从其名称中确定变量的类型。以is或has开头的变量假设为布尔类型，而callback、cb、done、fn和next假设是函数。如果你使用自己的变量命名系统（例如，匈牙利符号：布尔值都以b开头，数组以arr开头），你可以自己定义这些规则。使用jsdocs_notation_map设置，例如

{
    "jsdocs_notation_map": [
        {
            "prefix": "b", /* a prefix, matches only if followed by an underscore or A-Z */
            "type": "bool" /* translates to "Boolean" in javascript, "bool" in PHP */
        },
        {
            "regex": "tbl_?[Rr]ow", /* any arbitrary regex to test against the variable name */
            "type": "TableRow"      /* you can add your own types */
        }
    ]
}

注释图也可以用于添加任意标签，根据你自己的代码约定。例如，如果你的约定表明以下划线开头的函数是私有的，你可以将其添加到jsdocs_notation_map中

{
    "prefix": "_",
    "tags": ["@private"]
}

注释扩展

在docblock内部按enter键将自动插入一个前置星号并保持你的缩进。

这适用于docblock注释/** like this */以及内联双斜杠注释// like this

在两种情况下，你也可以按shift+enter键停止自动扩展。

在记录参数或为标签添加描述时，您的描述通常会跨越多行。如果您所在的行为直接跟在一个标签行之后，按下 Tab 键会将缩进移动到正确的位置。

注释装饰

如果您编写了双横线注释并按下 Ctrl+Enter，DocBlockr 会自动对该行进行 '装饰'。

// Foo bar baz<<Ctrl+Enter>>

-- becomes

/////////////////
// Foo bar baz //
/////////////////

您可以通过将 jsdocs_decorate 设置更改为 false 来禁用此功能。

重新解析 DocBlock

有时，您执行某些操作可能会清除字段（使用 Tab 键可以导航的文本部分）。这将使您在 DocBlock 中留下若干占位符，而没有简单的方法可以直接跳转到它们。

在 DocBlockr 中，您可以按热键 Alt+Shift+Tab（在 OS X 或 Linux 中）或 Alt+W（在 Windows 中）重新解析注释并重新激活字段。

重新格式化段落

在注释块中，按 Alt+Q 键可以折叠行以适应您的标尺。如果您想让段落中的后续行缩进，您可以调整 jsdocs_indentation_spaces_same_para 设置。例如，值为 3 时可能会这样显示

/**
 * Duis sed arcu non tellus eleifend ullamcorper quis non erat. Curabitur
 *   metus elit, ultrices et tristique a, blandit at justo.
 * @param  {String} foo Lorem ipsum dolor sit amet.
 * @param  {Number} bar Nullam fringilla feugiat pretium. Quisque
 *   consectetur, risus eu pellentesque tincidunt, nulla ipsum imperdiet
 *   massa, sit amet adipiscing dolor.
 * @return {[type]}
 */

添加额外标签

最后，在注释块中输入 @ 将显示 JSDoc 支持的所有标签的完成列表，包括 JSDoc，Google Closure Compiler，YUIDoc 或 PHPDoc。每个标签都有预先填充的参数提供额外帮助。按下 Tab 键将光标移动到下一个参数。

配置

您可以通过选择 首选项 -> 插件设置 -> DocBlockr 来访问配置设置。

jsdocs_* 前缀是过去的遗留下来的...

• jsdocs_indentation_spaces (数字) 在起始星号之后的空格数。

  // jsdocs_indentation_spaces = 1
  /**
   * foo
   */
  
  // jsdocs_indentation_spaces = 5
  /**
   *     foo
   */
  

• jsdocs_align_tags (字符串) 接在标签后面的单词是否应该对齐。可能的值是 'no'，'shallow' 和 'deep'

  为了向后兼容，false 等同于 'no'，true 等同于 'shallow'

  'shallow' 将仅对标签后面的第一词进行对齐。例如

  @param    {MyCustomClass} myVariable desc1
  @return   {String} foo desc2
  @property {Number} blahblah desc3
  

  'deep' 将对标签的每个组成部分进行对齐。例如

  @param    {MyCustomClass} myVariable desc1
  @return   {String}        foo        desc2
  @property {Number}        blahblah   desc3
  

• jsdocs_extra_tags (字符串数组) 一个字符串数组，每个字符串代表要添加到 函数 的额外样板注释。这些也可以包括任意文本（不仅仅是标签）。

  // jsdocs_extra_tags = ['This is a cool function', '@author nickf', '@version ${1:[version]}']
  /**<<enter>>
  function foo (x) {}
  
  /**
   * [foo description]
   * This is a cool function
   * @author nickf
   * @version [version]
   * @param  {[type]} x [description]
   * @return {[type]}
   */
  function foo (x) {}
  

  此处支持基本变量替换，对于 date 和 datetime 等变量，用大括号括起来。

  // jsdocs_extra_tags = ['@date {{date}}', '@anotherdate {{datetime}}']
  /**<<enter>>
  function foo() {}
  
  /**
   * [foo description]
   * @date     2013-03-25
   * @datetime 2013-03-25T21:16:25+0100
   * @return   {[type]}
   */
  

• jsdocs_extra_tags_go_after (布尔值) 如果为真，则将额外标签放置在块的末尾（在 param/return 之后）。默认值：false

• jsdocs_extend_double_slash (布尔值) 双斜杠注释是否应该扩展。本节上述已描述该功能示例。默认值：true

• jsdocs_deep_indent (布尔值) 是否在 docblock 中按行首的 Tab 键时应该缩进以匹配前一行描述字段。本节上述已描述该功能示例。默认值：true

• jsdocs_notation_map (数组) 一个表示符号对象的数组。每个符号对象必须定义 prefix 或 regex 属性，以及一个 type 属性。

• jsdocs_return_tag (字符串) 应用于 @return 标签的文本。默认情况下，使用 @return，但您可以将其更改为 @returns 如果您使用那种风格。

• jsdocs_spacer_between_sections (布尔值/字符串) 如果为真，则在 docblock 的节之间插入额外的空白行。如果设置为 "after_description"，则仅在描述和第一个标签之间添加间隔。默认值：false

• jsdocs_indentation_spaces_same_para (数字) 在《段落重新格式化》部分中已描述。默认值：1

• jsdocs_autoadd_method_tag (布尔) 将 @method 标签添加到函数的 docblocks 中。默认值：false

• jsdocs_simple_mode (布尔) 如果为真，DocBlockr 在函数或变量之前创建 docblock 时不添加模板。如果您不想用 Javadoc 风格编写，但仍然希望编辑器在编写块注释时提供帮助，这将很有用。默认值：false

• jsdocs_lower_case_primitives (布尔) 如果为真，则将原始数据类型添加为小写，例如“number”而不是“Number”。默认值：false

• jsdocs_short_primitives (布尔) 如果为真，则原始数据类型 Boolean 和 Integer 被缩短为 Bool 和 Int。默认值：false

• jsdocs_newline_after_block (布尔) 如果为真，则在 docblock 结尾后添加额外的换行符，以将其与代码分离。默认值 false

• jsdocs_param_name (布尔) 如果为真，则将函数参数的名称添加到模板中。如果为假，则省略。默认值：true

• jsdocs_decorate (布尔) 如果为假，则禁用使用 Ctrl+Enter 装饰单行注释。默认值：true

• jsdocs_quick_open_inline (布尔) 如果为真，在按下开头的 /** 后按下 Space 时将打开内联 docblock。当设置为 false 时，可以通过按下 Shift+Enter 打开。默认值：true

• jsdocs_function_description (布尔) 如果为真，将为函数添加 'description' 行。默认值：true

贡献者

本包是由 Nick Fisher 创建的，但其他人也做出了许多贡献。请查看 贡献者列表，以了解其他应该得到感谢的人。