Customization

Settings

Understanding settings

DoxyDoxygen is highly configurable. This section aims to help to understand the global philosophy.

Take an example: You develop in Php and you want to use the Drupal API Module style. Drupal has NOT the same set of commands that PhpDoc, so you have to change the doc-style.

The job to map programming language to a doc-style is done by profiles. The new section will look like this:

"profiles": [
    {
        "languages":  [ "php" ],
        "parsers":    [ "LanguagePhp" ],
        "doc_styles": [ "Drupal" ] // instead of "PhpDoc"
    }
],

  • languages is the list of sublime text affected syntaxes. To get a language name, use the integrated agent, then look for doxy.language and add the value to the list.
  • parsers is the list of programming language parsers. First is preferred. Copy this settings from “Default Settings” or use LanguageGeneric for aliens ones.
  • doc_styles is the list of doc-styles. First item is use on comment creation. Others only add commands for completion.

Now consider that you want to add information about exceptions. The presence and the order of the tags is defined by block_layout. The new section will look like this:

"block_layout": {
    "Drupal": [
        "",
        "@_brief",
        "",
        "@param",
        "",
        "@return",
        "",         // added line (to force a blank line before @throws)
        "@throws",  // added line
        ""
    ]
},

The block_layout section don’t help to fix command formatting… For example, to remove columns alignment, you have to set preferred_tabs_sizes:

"preferred_tabs_sizes": [ 0 ],

Settings references

The default configuration file is highly commented, this section is an extract of those informations.

debug_enabled (default is false)
Turn on logs in console.
completion_enabled (default is true)
Enable/Disable internal commands completion.
completion_use_aliases (default is true)
Add aliases to completions suggestions.
completion_snippet_format (default is "default")
Change the way snippets are generated.
Possibles values are:
  • default: current preferred (may be one of the following values)
  • pedagogic: optional arguments generate a tab stop
  • remove_optional: assumed optional is not optional
continuation_on_last_multilines_comment (default is true)
If true, pressing on Enter on the last comment line of multilines comments inserts a new comment line. To break this sequence, you have to press Shift+Enter or Down.
continuation_on_singleline_comment (default is false)
If true, pressing on Enter on the end of a single line comment inserts a new comment line. To break this sequence, you have to press Shift+Enter or Down.
distance_for_bottom_line_over_top_line (default is 3)
The DoxyCommentNearestEntity command uses this value to locate the “nearest” function. If the value is 3, the plug-in prefers go up to 2*3-1=5 lines up, instead of 2 lines down.
doxygen_command_prefix (default is "@")
Preferred command prefix (@ is more common and shouldn’t be change, but can be \\ if you use QT Doc).
doxygen_discard_param_directions (default is false)
Doxygen allows to specify parameters directions (in, out). Sets this parameter to true to discard this information.
doxygen_paragraph_prefix (default is "\t")
Prefix before a paragraph.
Examples:
  • "\t": move to next column
  • "\n": move to a new line
  • "\n    ": move to a new line with an indentation
  • " ": add a space

Currently unaffected commands: @par, @todo, @xrefitem

doxygen_cmd (default is "doxygen")
Path to the Doxygen command.
Rules:
  • Can be absolute or relative
  • If path is relative, the plugin will look for the module in PATH
  • On Windows machines, the .exe suffix will be added if missing
c_macros
List of C, C++ macros to expand (python regexp supported as name)

Warning

Only macros without parameter are currently supported

jsdoc_paragraph_prefix (default is "\t")
Same as doxygen_paragraph_prefix for JsDoc (for example, Drupal uses "\n  ").
phpdoc_paragraph_prefix (default is "\t")
Same as doxygen_paragraph_prefix for JsDoc (for example, Drupal uses "\n  ").
phpdoc_short_primitives (default is false)
If true, the primitives “Boolean” and “Integer” are shortened to “Bool” and “Int”

Some tools, like PHP CODE SNIFFER, may require this option to work.

php_generate_fully_qualified_name (default is true)
Replace relative name with fully qualified name.

More details can be found in the GitHub request.

python_func_annotations_are_types (default is true)
Python annotation may be everything. Set this parameters to true to allow to use those values as parameter types.
remove_template_used_as_type (default is false)
If true, template <typename T1> void Bar(T1 x); will not generate a @tparam entry as T1 appear as type in parameters list.
brief_mode (default is "preserve")
Behavior for @brief: remove / preserve existing one.
indentation_max (default is 99999999)
Maximum indentation within a comment.

Note

This setting does NOT affect list items

Example with the value ‘2’
 /**
 * Find players in the game.
 *
 * @param string $filter Name of the filter. 'registered' to return only
 *   registered players. Leave empty to return all players.
 * ^
 * +----- indentation is 2 spaces here
 */
Example with the value ‘9999999’ (or any number greater than 22)
 /**
 * @param string $filter Name of the filter. 'registered' theo return only
 *                       registered players. Leave empty to return all
 *                       players.
 * ^
 * +----- indentation is 22 spaces here
 */
min_spaces_between_columns (default is [ 1, 2 ])
Minimum spaces between columns.

Warning

The value CANNOT be an empty list.

Rules:
  • First number is for first column
  • Second number is for second column
  • Last number is applied to all next columns
Example with the value ‘[1, 2]’
             +-- At least 1 space here (but according ``preferred_tabs_sizes`` it's more)
/**          V    V--- At least 2 spaces here
 * @param[in]  foo       Lorem ipsum dolor sit amet.
 * @param[out] long_bar  Nullam fringilla feugiat pretium. Quisque
 */
preferred_tabs_sizes (default is [ 12, 6, 8, 8, 8, 8 ])
Default tabs size in documentation block (last value is repeated if needed). You can use [ 0 ] to treat tabs as spaces (and disable alignment).

Warning

The value CANNOT be an empty list.

Example with the value ‘[ 13, 6, 8, 8, 8, 8 ]’
/**
 * @param[in]  a     { parameter_description }
 * 123456789012      12345678...and continue because there is no more tab
 *             123456
 */
group_tabs_sizes_by (default is "comment")
Way that tabs size are computed.
Possibles values:
  • “comment” to align tabs in the whole comment
  • “section” to align tabs in each group of command separated with a blank line separatly (added in version 0.61.0)

See How to set max space

preferred_line_length (default is "auto")
DoxyDoxygen parameter to set the preferred line length (line will be wrapped if there are greater than this limit)

If not set or “auto”, the value used is the first value of the SublimeText rulers parameter (default: 80 if empty).

max_line_reducing (default is 12)
Maximum number of characters that a line may be reduced to respect the rulers.
merge_matching_ratio (default is 0.6)
Matching ratio to consider two keys similar.
It’s a value from 0 to 1:
  • 1 is exact match,
  • 0.6 is close match.

For example:

/** @param  misstake  Name in comment has two 'ss'
 */
void function(int mistake);

With merge_matching_ratio set to 0.6, on update, as misstake similar to mistake, the comment will directly become:

/* @param  mistake    Name in comment has two 'ss'
 */
void function(int mistake);
preserve_aliases (default is false)
If false, replace aliases with the main command.
preferred_comments_styles
List of possible styles for comments (first match is better).
block_layout_default
Positioning of the commands that can be present in the documentation block.

See block_layout for further informations on format.

Warning

SHOULD NOT BE OVERLOAD BY USER (use block_layout instead)

block_layout (default is {)
Used to overload block_layout_default values.

Warning

The section define commands positionning (and optionaly default value). Do NOT try to use it to format command.

Values can be either:
  • an array of tags for rigid layout
  • an array of dictionaries for context dependent layout
If value is an array of tags (strings):
  • Tags may be command or blank lines.
  • Doxygen like commands must be prefixed with @ or \
  • Commands arguments are in the python format() style
  • In addition of standard format specifiers, some have been added:
    • doxy_words(start[, end[, step]); (work as python arrays [start:end:step])
    • doxy_chars(start[, end[, step]); (work as python arrays [start:end:step])
    • doxy_capitalize();
    • doxy_upper();
    • doxy_lower();
    • doxy_a(); (add a or an before the word)
    • doxy_A(); (add A or An before the word)
    • doxy_the(); (add the before the word)
    • doxy_The(); (add The before the word)
    • doxy_plural();
    • doxy_conjugate();
    • doxy_undecorate(); (remove prefix: Hungarian notation)
  • Commands arguments may include:
    • documented item information: name, kind, nb_params, nb_tparams
    • data information: now or utc_now (see example below)
    • path information: file_base_name, file_full_name, file_name, file_path
    • project information: project_base_name, project_full_name, project_name, project_path
    • context information: user_name, host_name, language
  • Special command @_brief may be used to ask for item description without prefix
If value is a dictionary, it should have 2 keys:
Each context is a list of conditions. Each condition is composed of
  • key: Name of the context whose value you want to query.
  • operator: Type of test to perform against key’s value.
Possibles values for key:
  • name: Name of the entity to document
  • kind: Kind of the entity to document
    • function, lambda, generator, constructor, destructor,
    • class, struct, union, enum,
    • var, constant
  • nb_params: Number of parameters (destructing params group “{ first, second }” count as 1 parameters)
  • nb_tparams: Number of template parameters
  • row: Cursor row
  • col: Cursor column
Possibles values for operator (Defaults to equal):
  • equal
  • not_equal
  • regex_match: Match against a regular expression (full match).
  • not_regex_match
  • regex_contains: Match against a regular expression (partial match).
  • not_regex_contains
  • greater_than
  • lower_than
proxies
Defines for each protocol a proxy settings.

If the dictionnary is empty, system defaults are used.

Possibles values:
  • <package_control> uses package control settings
  • joe:password@proxy.example.com:3128 define specific proxy
translators
The list of translation services (first is preferred).
source_languages (default is [])
The list of languages that can be present in your source (or auto)

If the list is not empty and not the target language, a conversion may be perform (this can slow down update)

Examples:
  • auto Auto-detection
  • [] Disable translation of non-generated text
  • ["de", "fr"] German or French (currently same as auto)
target_language (default is "en")
Preferred language in generated comments (also used as default translation target).

The format is based on ISO_639-1 format with Google extension.

Examples:
  • ar Arabic
  • de German
  • es Spanish
  • fr French
  • it Italian
  • pt Portuguese
  • ru Russian
  • zh-CN Chinese (simplified)
  • zh-TW Chinese (traditional)
  • hmn Hmong
  • ceb Cebuano
autofill_rules_default
DoxyDoxygen can automatic fill some descriptions. Here the default rules used to do it.

To disallow auto-fill, you may override it with an empty array.

autofill_rules
Used to overload autofill_rules_default values.

If you want to disable parameters description (common request), you can try:

"autofill_rules": [
    {
        "parameter_description": [
            "."
        ]
    }
],
word_expansions
Used to overload internal word expansions (words must be lower-case)

If you want to disable an internal expansions simply add it here.

autofill_reliability_percentage (default is 60)
Default reliability for generated text.
Should be:
  • 0: disable auto-fill (default and custom)
  • 60: text is generated only if none found in source WITH a tab stop
  • 100: text is generated only if none found in source WITHOUT tab stop
  • 101: generated text override source one
profiles_default
For each Sublime Text language, give the preferred parser and documentation style (also called “documentation generator”).
profiles
Used to overload profiles_default values.
doc_styles
Used to ease overload commands

New in version 0.70.0.

Warning

EXPERIMENTAL. Only supports ApiDoc, AsDoc, DoxyDoc, Doxygen, Drupal, JavaDoc, JsDoc, PhpDoc, PhpUnitDoc, SassDoc, Solidity for now

Note

This setting may require SublimeText restart to take effect

Project Specific Settings

To define Project Specific Settings, you can edit the .sublimetext-project file and add a DoxyDoxygen section in the settings section. All settings can be overloade. Project Settings overload the User Settings.

{
    /* projects field */

    "settings":
    {
        /* Others plugins and SublimeText settings */

        "DoxyDoxygen": {
            "merge_matching_ratio": 0.5,
        }
    }
}

Translation services settings

New in version 0.68.0.

To add a translation service, append an entry to translators settings. The first entry is the preferred one.

Each entry is a dictionnary. This section describes for each translator service, the available keys and their meaning.

Google

  • Used by default
Settings description:
  • provider: "google" (mandatory)
  • api_key: Your API key

Bing

Settings description:
  • provider: "bing" (mandatory)
  • client_id: Your client identifier
  • client_secret: Your secret identifier for this service

SDL Language Cloud

  • Require a SDL account
  • For Machine Translation you can use up to 500,000 characters per month in Sandbox for free.
Settings description:
  • provider: "sdl" (mandatory)
  • api_key: Your API key

Frengly

Settings description:
  • provider: "frengly" (mandatory)
  • email: Your email
  • password: Your password for this service

Yandex

Settings description:
  • provider: "yandex" (mandatory)
  • key: Your API key
  • user: Your client identifier
  • pass: Your password for this service

MyMemories

Warning

Contrary to MyMemories statements, email and user seem to have no effect on translation limitation

Settings description:
  • provider: "mymemories" (mandatory)
  • email: Your email
  • user: Your client identifier
  • pass: Your password for this service

Baidu

Settings description:
  • provider: "baidu" (mandatory)
  • app_id: Your client identifier
  • secret_key: Your secret identifier for this service

Youdao

Settings description:
  • provider: "youdao" (mandatory)
  • key_from: Your client identifier
  • secret_key: Your secret identifier for this service

Hablaa

  • Currently word by word but large languages support.
Settings description:
  • provider: "hablaa" (mandatory)

LiguaSys

  • Require a LinguaSys account, 3 steps:
  • Limited free translations (up to 20 API calls a minute, and up to 500 calls a month).
Settings description:
  • provider: "linguasys" (mandatory)
  • secret_key: Your secret identifier for this service

Add your own doc-style

DoxyDoxygen may be extended by plug-in. Plug-in currently allow to define your own doc-style. See HeaderDoc example for further informations.

Key bindings

This plug-in come with few keyboard shortcuts (to prevent conflict with others plug-ins). But, key bindings are configurable. Please refer to Sublime Text official documentation for further informations.

This section describes the key bindings added by default in DoxyDoxygen.

Key bindings on Windows and Linux

  • Enter : doxy_enter()
  • Enter (keypad) : doxy_enter()
  • Shift+Enter : doxy_chain_commands(commands=[['view.move_to', OrderedDict([('to', 'hardeol'), ('extend', False)])], ['view.doxy_enter']])
  • Ctrl+Shift+Enter : doxy_chain_commands(commands=[['view.move_to', OrderedDict([('to', 'hardbol'), ('extend', False)])], ['view.move', OrderedDict([('by', 'characters'), ('forward', False)])], ['view.doxy_enter']])
  • End : doxy_go_to_eol()
  • Ctrl+Shift+[ : doxy_fold_comments(action=fold)
  • Ctrl+Shift+] : doxy_fold_comments(action=unfold)
  • Alt+Q : doxy_comment_nearest_entity()
  • Shift+Alt+Q : doxy_update_comments(reparse=True, new_style=roll_2)
  • Alt+Q : doxy_update_comments(reparse=True)

Key bindings on OS X

In the table below Super refers to the Command key (marked with the symbol)

  • Enter : doxy_enter()
  • Enter (keypad) : doxy_enter()
  • Super+Enter : doxy_chain_commands(commands=[['view.move_to', OrderedDict([('to', 'hardeol'), ('extend', False)])], ['view.doxy_enter']])
  • Super+Shift+Enter : doxy_chain_commands(commands=[['view.move_to', OrderedDict([('to', 'hardbol'), ('extend', False)])], ['view.move', OrderedDict([('by', 'characters'), ('forward', False)])], ['view.doxy_enter']])
  • Super+Right : doxy_go_to_eol()
  • Super+Alt+[ : doxy_fold_comments(action=fold)
  • Super+Alt+] : doxy_fold_comments(action=unfold)
  • Super+Alt+Q : doxy_comment_nearest_entity()
  • Super+Shift+Alt+K : doxy_update_comments(reparse=True, new_style=roll_2)
  • Super+Alt+Q : doxy_update_comments(reparse=True)

Commands from the palette

A lot of commands are only available from the Command Palette.

To open the Command Palette
  • on Windows or Linux, press Ctrl+Shift+P
  • on OS X, press Super+Shift+P

This section describes the commands added by default in DoxyDoxygen.

  • DoxyDoxygen: Comment Wrap : doxy_update_comments(reparse=False)
  • DoxyDoxygen: Comment Update Preserving Style : doxy_update_comments(reparse=True)
  • DoxyDoxygen: Update Comment With Preferred Style : doxy_update_comments(reparse=False, new_style=preferred)
  • DoxyDoxygen: Update Comment With User-Selected Style (interactive)… : doxy_update_comments(reparse=False, new_style=user_select)
  • DoxyDoxygen: Comment All : doxy_comment_all()
  • DoxyDoxygen: Select Comments (interactive)… : doxy_select_comments(kind=user_select)
  • DoxyDoxygen: Fold All Comments : doxy_fold_comments(action=fold, scope=file)
  • DoxyDoxygen: Unfold All Comments : doxy_fold_comments(action=unfold, scope=file)
  • DoxyDoxygen: Send Report : doxy_send_report()
  • DoxyDoxygen: Build Documentation : doxy_build_documentation()
  • DoxyDoxygen: Tutorial : doxy_tutorial()
  • DoxyDoxygen: Translate Selection : doxy_translate()
  • DoxyDoxygen: Translate Selection To… : doxy_translate(target_language=user_select)
  • Preferences: DoxyDoxygen Settings : doxy_edit_settings(base_file=${packages}/${module_name}/Doxy.sublime-settings, user_file=${packages}/User/Doxy.sublime-settings)
  • Preferences: DoxyDoxygen Key Bindings : doxy_edit_settings(base_file=${packages}/${module_name}/Default (${platform}).sublime-keymap, user_file=${packages}/User/Default (${platform}).sublime-keymap)

Commands from the menu

Alternatively to the Command Palette, some commands are also available from the menu. Go to Preferences ‣ Package Settings ‣ DoxyDoxygen to launch them.

Available commands:

  • Settings : doxy_edit_settings(base_file=${packages}/${module_name}/Doxy.sublime-settings, user_file=${packages}/User/Doxy.sublime-settings)
  • Key Bindings : doxy_edit_settings(base_file=${packages}/${module_name}/Default (${platform}).sublime-keymap, user_file=${packages}/User/Default (${platform}).sublime-keymap)
  • Commands from the palette : doxy_edit_settings(base_file=${packages}/${module_name}/Doxy.sublime-commands, user_file=${packages}/User/Default.sublime-commands)
  • Purchase License : doxy_buy()
  • Enter License : doxy_register()
  • Remove License : doxy_unregister()

Note

License commands are only available from the menu