自然文档

SublimeText 2的自然文档包

详细信息

版本 2015.12.10.16.26.20
主页自然文档
问题 github.com
修改 9 年前
最近查看 1 分钟前
首次查看 13 年前

安装

总数 735
Win 268
Mac 337
Linux 130

	8月6日	8月5日	8月4日	8月3日	8月2日	8月1日	7月31日	7月30日	7月29日	7月28日	7月27日	7月26日	7月25日	7月24日	7月23日	7月22日	7月21日	7月20日	7月19日	7月18日	7月17日	7月16日	7月15日	7月14日	7月13日	7月12日	7月11日	7月10日	7月9日	7月8日	7月7日	7月6日	7月5日	7月4日	7月3日	7月2日	7月1日	6月30日	6月29日	6月28日	6月27日	6月26日	6月25日	6月24日	6月23日
Windows	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0
Mac	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0
Linux	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0

说明

源码: raw.githubusercontent.com

自然文档是一个Sublime Text 2包，使得编写自然文档变得容易。基于由Nick Fisher编写的DocBlockr，受到Germán M. Bravo的SublimeLinter的启发。

语言

目前支持的语言：CoffeeScript、Java、JavaScript、Perl、PHP、Python 和 Matlab（仅限于注释装饰）。

用法

使用此插件的简单方法是将光标移至您想要文档的位置，然后按Super+N（或OS X上的Super+N + Super+N）。

自动完成注释

如果您开始一个注释块（例如 /*、/**、/*!）并按回车，它将完成该块并将光标置于中间。随后，在块内按回车将在下一行继续注释块。

/**| -> Enter

结果如下

/**
 * |
 */

上面的竖线表示光标。再次按Enter将结果变为以下内容

/**
 *
 * |
 */

如果您在一个函数之前开始了一个块，它将填充函数信息。

/** |
function testThis($one, $two) {}

结果如下

/**
 * Function: testThis
 *
 * |description
 *
 * Parameters:
 *
 *   $one - [type/description]
 *   $two - [type/description]
 *
 * Returns:
 *
 *    return description
 */
function testThis($one, $two) {}

单行注释

此外，如果您开始一个单行注释（例如 // 或 #），按回车将在下一行继续注释块。您也可以按Shift-Enter跳转到空白行。

装饰

您可以通过按Ctrl-Enter添加装饰块。

JavaScript中的示例

// this is a pretty item |

结果如下

///////////////////////////
// this is a pretty item //
///////////////////////////

Perl中的示例

# this is a pretty item |

结果如下

#########################
# this is a pretty item #
#########################

特定语言的示例

CoffeeScript示例

类示例

示例

class Animal

结果

#
# Class: Animal
#
# [Animal description]
#
class Animal

示例

class Snake extends Animal

结果

#
# Class: Snake
#
# [Snake description]
#
# Extends: Animal
#
class Snake extends Animal

函数示例

示例

square = (x) -> x * x

结果

#
# Function: square
#
# description
#
# Parameters:
#
#   x - [type/description]
#
# Returns:
#
#   return description
#
square = (x) -> x * x

示例

race = (winner, runners...) ->

结果

#
# Function: race
#
# description
#
# Parameters:
#
#   winner  - [type/description]
#   runners - Splat.
#
# Returns:
#
#   return description
#
race = (winner, runners...) ->

示例

fill = (container, liquid = "coffee") ->

结果

#
# Function: fill
#
# description
#
# Parameters:
#
#   container - [type/description]
#   liquid    - String. Defaults to "coffee"
#
# Returns:
#
#   return description
#
fill = (container, liquid = "coffee") ->

Java示例

类

public class MyClass extends BaseClass implements ClassA, ClassB { ... }

将光标放在行上或之前，然后按Super+N将导致以下结果

/**
 * Class: MyClass
 *
 * [MyClass description]
 *
 * Extends: BaseClass
 *
 * Implements: ClassA, ClassB
 */
public class MyClass extends BaseClass implements ClassA, ClassB { ... }

构造函数

public MyClass() { ... }

结果如下

/**
   * Constructor: MyClass
   *
   * description
   */
  public MyClass() { ... }

方法

public Map<String, String> methodOne(Map<String, String> one, List<Map<String, String>> two, char[] three, int four)  { ... }

结果如下

/**
   * Method: methodOne
   *
   * description
   *
   * Parameters:
   *
   *   one   - Map<String,String>
   *   two   - List<Map<String,String>>
   *   three - char[]
   *   four  - int
   *
   * Returns:
   *
   *   Map<String, String> - return description
   */
  public Map<String, String> methodOne(Map<String, String> one, List<Map<String, String>> two, char[] three, int four) { ... }

JavaScript示例

代码

function testThis($one, $two, $three) {}

将光标放在行上或之前，然后按Super+N将导致以下结果

/**
 * Function: testThis
 *
 * description
 *
 * Parameters:
 *
 *   $one   - [type/description]
 *   $two   - [type/description]
 *   $three - [type/description]
 *
 * Returns:
 *
 *    return description
 */
function testThis($one, $two, $three) {}

Perl示例

包代码

package A::B::C;

将光标放在行上或之前，然后按Super+N将导致以下结果

=begin ND

Package: A::B::C

[A::B::C description]

=cut
package A::B::C;

函数代码

sub index { ... }

结果如下

=begin ND

Function: index

description

Returns:

   return description

=cut
sub index { ... }

PHP示例

类

<?php
class ClassD extends ClassA implements ClassB, ClassC { ... }

将光标放在行上或之前，然后按Super+N将导致以下结果

<?php
/**
 * Class: ClassD
 *
 * [ClassD description]
 *
 * Extends: ClassA
 *
 * Implements: ClassB, ClassC
 */
class ClassD extends ClassA implements ClassB, ClassC { ... }

功能

<?php
function testThis($one='', $two=true, $three=array()) {}

结果如下

<?php
/**
 * Function: testThis
 *
 * description
 *
 * Parameters:
 *
 *   $one   - string
 *   $two   - boolean
 *   $three - array
 *
 * Returns:
 *
 *    return description
 */
function testThis($one='', $two=true, $three=array()) {}

Python 示例

类代码

class ClassB(ClassA):

将光标放在或/之后/该行并按 Super+N 将得到

class ClassB(ClassA):
  """
  Class: ClassB

  [ClassB description]

  Extends: ClassA
  """

函数代码

def test_test(one, two=12, three=[]):
    return 'yes'

结果如下

def test_test(one, two=12, three='something'):
    """
    Function: test_test

    description

    Parameters:

      one   - [type/description]
      two   - integer
      three - string

    Returns:

       return description
    """
    return 'yes'

命令

NaturalDocsCommand
NaturalDocsInsertBlock
NaturalDocsIndentCommand
NaturalDocsJoinCommand
NaturalDocsDecorateCommand

设置

natural_docs_deep_indent

此设置控制是否根据前一行对文档块内的行进行对齐。

在文档块内部使用 Enter 时，NaturalDocs 将尝试将下一行的起始位置对齐到：

示例

/**
   * ...
   * Parameters:
   *
   *   one     - this parameter does something |
   *   twoLong - string
   */

如果当前包含 ' - ' 的行，则按 Enter 将插入足够的空格以对齐光标到上一行的描述。结果

/**
   * ...
   * Parameters:
   *
   *   one     - this parameter does something
   *             |
   *   twoLong - string
   */

同样，如果当前行不包含 ' - '，则按 Enter 将插入足够的空格以在文档内部的第一非空白字符下开始新行。开始于

/**
   * ...
   * Parameters:
   *
   *   one     - this parameter does something
   *             this is another line |
   *   twoLong - string
   */

结果如下

/**
   * ...
   * Parameters:
   *
   *   one     - this parameter does something
   *             this is another line
   *             |
   *   twoLong - string
   */

如果启用了此设置，并且文档块中没有任何片段字段可用，您也可以使用 Tab 插入所需数量的空格，将光标放在上一行的描述之下。

/**
   * ...
   * Parameters:
   *
   *   one   - this parameter does something
   * |
   */

按 Tab 将得到

/**
   * ...
   * Parameters:
   *
   *   one   - this parameter does something
   *           |
   */

natural_docs_continue_comments

如果此设置设置为 True，则在带有双斜杠或井号注释的行上按 Enter 将将该注释标点置于下一行的开头。

示例

// hello |

转换为

// hello
// |

natural_docs_indentation_spaces

在注释标点之后插入空格的数量。例如，设置为 1

/**
 * Function: <functionName>

设置为 5 的示例

/**
 *     Function: <functionName>

默认为 1。

natural_docs_spacer_between_sections

如果设置为 true，则将在文档块之间的部分添加额外的行。例如

/**
 * Function: <functionName>
 *
 * [description]
 *
 * Parameters:
 *
 *    foo - [description]
 *    bar - [description]
 *
 * Returns:
 *
 *    [description]
 */

如果设置为 false，则将使文档块更为紧凑。例如

/**
 * Function: <functionName>
 * [description]
 * Parameters:
 *    foo - [description]
 *    bar - [description]
 * Returns:
 *    [description]
 */

natural_docs_perl_use_pod

如果设置为 true，将使用 POD 风格的注释而不是使用 Perl 的井号注释。例如

=begin ND

Function: <functionName>

[description]

Parameters:

   foo - [description]
   bar - [description]

 Returns:

   [description]

=cut

如果设置为 false，则将使用正常的注释标签。例如

#
# Function: <functionName>
#
# [description]
#
# Parameters:
#
#    foo - [description]
#    bar - [description]
#
#  Returns:
#
#    [description]
#

natural_docs_language_map

此设置将当前语法源映射到 NaturalDocs 解析器。要确定源文件名，请按 Ctrl+Alt+Shift+P，然后在状态行中会出现作用域树。NaturalDocs 解析该字符串以查找 “source.(\w+)” 并使用括号内的部分进行映射。

此外，映射中还有一个后备占位符“_”。这是一种让 NaturalDocs 默认使用特定解析器的方法，如果

待办事项

添加更多语言（C/C++、Ruby）
为 PHP5.4 准备一些特殊功能（可能解析类似于类的特性？）
使其更加出色

变更日志

2013 年 5 月 14 日

添加了一个将源语言映射到 NaturalDocs 解析器的新设置
NaturalDocs 仅在新的设置中映射源文件时才工作

2012 年 12 月 7 日

添加了 CoffeeScript 解析器

2012 年 7 月 9 日

修复了如果语言喜欢在要注释的内容下方注释（例如 Python）时的错误行注释问题
添加了一个自定义 EventListener，用于检查来自键映射上下文的 NaturalDocs 设置
已解决问题 #4：Tab 覆盖了 next_field 动作。

2012 年 6 月 29 日

已解决问题 #6：当直接在 EOF 之上插入文档块时不起作用。
修复了新首选项文件无法始终正确使用的问题（特别是对于非 JavaScript 类似语言）

2012 年 6 月 11 日

已解决问题 #5：将设置文件移动到 NaturalDocs.sublime-settings / User/NaturalDocs.sublime-settings

2012 年 5 月 15 日

已修复问题 #3：在 EOF 上方直接插入 doc-blocks 时无法工作
修复了当解析器使用时插入 Group block 的Bug
修改了 OS X 的默认快捷键映射

2012 年 4 月 11 日

将所有解析器的函数名转换为蛇形命名
向 BaseParser 添加了 __getattr__，以便外部类访问语言设置

2012 年 4 月 9 日

添加了 Java 解析器（更新了 BaseParser 以提高其健壮性）
修复了装饰命令的缩进Bug
修复了 PHP 解析器的 Bug。类解析器不会将 implements 添加到 docblock 中
修复了快捷键映射，natural_docs_deep_indent 和 NaturalDocsIndentCommand 以确保其能够工作

2012 年 3 月 21 日

为 Perl 和 Python 添加了装饰
添加了添加类/包 doc-blocks 的功能
将设置 natural_docs_extend_double_slash 修改为 natural_docs_continue_comments
如果 natural_docs_continue_comments 为 True，则添加快捷键映射以继续数字符号注释