NaturalDocs is a Sublime Text 2 package which makes writing NaturalDocs easy. Based on DocBlockr by Nick Fisher, influenced by Germán M. Bravo's SublimeLinter.
Currently supported languages: CoffeeScript, Java, JavaScript, Perl, PHP, Python and Matlab (only comment decoration).
The easiest way to use this plugin is to put the cursor near what you want to document and press Super+N
(or Super+N
+ Super+N
for OSX).
If you start a comment block (e.g. /*
, /**
, /*!
) and press enter, it will complete the block and put your cursor in the middle. Subsequently, pressing enter inside a block will create a new line continuing the comment block.
/**|
-> Enter
Results in
/**
* |
*/
The above pipe represents the cursor. Pressing Enter
again will result in this:
/**
*
* |
*/
If you happened to start a block before a function, it would populate the block with the function information.
/** |
function testThis($one, $two) {}
Results in:
/**
* Function: testThis
*
* |description
*
* Parameters:
*
* $one - [type/description]
* $two - [type/description]
*
* Returns:
*
* return description
*/
function testThis($one, $two) {}
Single-line Comments
Additionally, if you start a single-line comment (e.g. //
or #
), pressing Enter
will continue the comment block on the next line. You can press Shift-Enter
to just go to a blank line.
You can add decoration blocks by pressing Ctrl-Enter
.
Examples in JavaScript:
// this is a pretty item |
Results in:
///////////////////////////
// this is a pretty item //
///////////////////////////
Examples in Perl:
# this is a pretty item |
Results in:
#########################
# this is a pretty item #
#########################
Example:
class Animal
Result:
#
# Class: Animal
#
# [Animal description]
#
class Animal
Example:
class Snake extends Animal
Result:
#
# Class: Snake
#
# [Snake description]
#
# Extends: Animal
#
class Snake extends Animal
Example:
square = (x) -> x * x
Result:
#
# Function: square
#
# description
#
# Parameters:
#
# x - [type/description]
#
# Returns:
#
# return description
#
square = (x) -> x * x
Example:
race = (winner, runners...) ->
Result:
#
# Function: race
#
# description
#
# Parameters:
#
# winner - [type/description]
# runners - Splat.
#
# Returns:
#
# return description
#
race = (winner, runners...) ->
Example:
fill = (container, liquid = "coffee") ->
Result:
#
# Function: fill
#
# description
#
# Parameters:
#
# container - [type/description]
# liquid - String. Defaults to "coffee"
#
# Returns:
#
# return description
#
fill = (container, liquid = "coffee") ->
Class:
public class MyClass extends BaseClass implements ClassA, ClassB { ... }
Put cursor on or before the line and pressing Super+N
will result in:
/**
* Class: MyClass
*
* [MyClass description]
*
* Extends: BaseClass
*
* Implements: ClassA, ClassB
*/
public class MyClass extends BaseClass implements ClassA, ClassB { ... }
Constructor:
public MyClass() { ... }
Results in:
/**
* Constructor: MyClass
*
* description
*/
public MyClass() { ... }
Method:
public Map<String, String> methodOne(Map<String, String> one, List<Map<String, String>> two, char[] three, int four) { ... }
Results in:
/**
* 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) { ... }
Code:
function testThis($one, $two, $three) {}
Put cursor on or before the line and pressing Super+N
will result in:
/**
* Function: testThis
*
* description
*
* Parameters:
*
* $one - [type/description]
* $two - [type/description]
* $three - [type/description]
*
* Returns:
*
* return description
*/
function testThis($one, $two, $three) {}
Package Code:
package A::B::C;
Put cursor on or before the line and pressing Super+N
will result in:
=begin ND
Package: A::B::C
[A::B::C description]
=cut
package A::B::C;
Function Code:
sub index { ... }
Results in:
=begin ND
Function: index
description
Returns:
return description
=cut
sub index { ... }
Class:
<?php
class ClassD extends ClassA implements ClassB, ClassC { ... }
Put cursor on or before the line and pressing Super+N
will result in:
<?php
/**
* Class: ClassD
*
* [ClassD description]
*
* Extends: ClassA
*
* Implements: ClassB, ClassC
*/
class ClassD extends ClassA implements ClassB, ClassC { ... }
Function:
<?php
function testThis($one='', $two=true, $three=array()) {}
Results in:
<?php
/**
* Function: testThis
*
* description
*
* Parameters:
*
* $one - string
* $two - boolean
* $three - array
*
* Returns:
*
* return description
*/
function testThis($one='', $two=true, $three=array()) {}
Class Code:
class ClassB(ClassA):
Put cursor on or /after/ the line and pressing Super+N
will result in:
class ClassB(ClassA):
"""
Class: ClassB
[ClassB description]
Extends: ClassA
"""
Function Code:
def test_test(one, two=12, three=[]):
return 'yes'
Results in:
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'
This setting controls whether to align lines inside documentation blocks based on the previous line.
When using Enter
inside a documentation block, NaturalDocs will try to align the start of the next line either (1) after the parameter dash (space-hyphen-space) or (2) at the first actual start of last line. See examples.
Example:
/**
* ...
* Parameters:
*
* one - this parameter does something |
* twoLong - string
*/
If the current line that contains ' - ', then pressing Enter
will insert enough spaces to align the cursor under the description of the previous line. Result:
/**
* ...
* Parameters:
*
* one - this parameter does something
* |
* twoLong - string
*/
Similarly, if the current line does not contain ' - ', then pressing Enter
will insert enough spaces to start the line under the first non-Whitespace character inside the documentation. Starting at:
/**
* ...
* Parameters:
*
* one - this parameter does something
* this is another line |
* twoLong - string
*/
Results in:
/**
* ...
* Parameters:
*
* one - this parameter does something
* this is another line
* |
* twoLong - string
*/
If this setting is enabled, and there are no snippet fields available in the documentation block, you can also use Tab
to insert as many spaces as necessary to put the cursor below the description of the previous line.
/**
* ...
* Parameters:
*
* one - this parameter does something
* |
*/
Pressing Tab
results in:
/**
* ...
* Parameters:
*
* one - this parameter does something
* |
*/
If this setting is set to True
, then pressing Enter
on a line with a double-slash or number-sign comment will place that comment punctuation at the beginning of the next line.
Example:
// hello |
Translates to
// hello
// |
The number of spaces to insert after the comment punctuation. Example if set to one:
/**
* Function: <functionName>
Example if set to five:
/**
* Function: <functionName>
Defaults to one.
If set to true
will added extra lines between sections in docblock. For example:
/**
* Function: <functionName>
*
* [description]
*
* Parameters:
*
* foo - [description]
* bar - [description]
*
* Returns:
*
* [description]
*/
If set to false
will make the docblock more compact. Example:
/**
* Function: <functionName>
* [description]
* Parameters:
* foo - [description]
* bar - [description]
* Returns:
* [description]
*/
If set to true
will use POD-style comments instead of using Perl number-sign comments. Example:
=begin ND
Function: <functionName>
[description]
Parameters:
foo - [description]
bar - [description]
Returns:
[description]
=cut
If set to false
, the normal comment tag will be used. Example:
#
# Function: <functionName>
#
# [description]
#
# Parameters:
#
# foo - [description]
# bar - [description]
#
# Returns:
#
# [description]
#
This setting maps the current syntax source to a NaturalDocs parser. To determine the name of a source file press Ctrl+Alt+Shift+P
, and the scope tree will appear in the status line. NaturalDocs parses that string to find "source.(\w+)" and uses the part in parentheses to put in the map.
Additionally, there is a fallback placeholder in the map that is "_". This is a way to get NaturalDocs to default to a particular parser if either (1) the source language of the current file cannot be determined or (2) there is no other mapping for the source language. Example: if you like the way the Python NaturalDocs parser works and want to use that in all languages.
Tab
was overriding next_field
actions.NaturalDocs.sublime-settings
/ User/NaturalDocs.sublime-settings
__getattr__
to BaseParser
for external classes to access language settingsimplements
to docblocknatural_docs_deep_indent
, and NaturalDocsIndentCommand
to worknatural_docs_extend_double_slash
to natural_docs_continue_comments
natural_docs_continue_comments
is True