Customization

Settings

Understand the 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 multi-lines 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

Possibles values are:

  • @ (the default) is more common,

  • \` is an alternative used by 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

Warning

EXPERIMENTAL. Macros with parameters are partially supported (no “…”, no “#”, no “##”, no comment…)

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 true)

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 when the @brief tag is detected.

Possibles values are:

  • "preserve": to keep the @brief tag

  • "remove": to remove the @brief tag and make it implicit

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' the 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 are:

  • “comment” to align tabs in the whole comment

  • “section” to align tabs in each group of command separated with a blank line separately (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).

Each comment style is divided into 3 parts:

  • the header part

  • the inner part

  • the footer part

The header part is divided into 3 parts:

  • the beginning of the comment introducer

  • the repeated part of the comment introducer

  • the end of the comment introducer

For example:

["/*", "-", "*//**"],   // <=> /*-------------------*//**
The inner part is divided into 6 parts

  • the beginning of the line introducer

  • the repeated part of the line introducer

  • the end of the line introducer

  • the beginning of the line termination

  • the repeated part of the line termination

  • the end of the line termination

["/*", "*", " ", " ", "*", "*/"],   // <=> /************ <centered body here> ************/

The footer part is similar to the header part.

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 defines commands positioning (and optionally 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_ed(); (get the past participle of an infinitive verb)

    • doxy_undecorate(); (remove prefix: Hungarian notation)

    • doxy_operator_name(); (translate operator symbol to English words)

  • 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 a single parameter)

  • nb_tparams: Number of template parameters

  • paramX: The name of the Xth parameter (param1 for the first one)

  • 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 dictionary 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": [
            "."
        ]
    }
],
words_expansion

Used to overload internal words expansion (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.

Examples:

  • 0: disable auto-fill (‘default’ and ‘custom’ rules)

  • 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 commands overload

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, go to Project ‣ Edit Project. Then, edit the .sublimetext-project file and add a DoxyDoxygen section in the settings section. All settings can be overloaded. 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 dictionary. 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

LibreTranslate

  • A self-hosted translator based on argos-translate

  • An online service “https://libretranslate.com” also exist but require API-Key

Settings description:

Bing

  • Require an Azure account with Pay card

  • Free plan is only up to 2_000_000 characters per month (and 12 months max)

  • 60+ languages supported

  • Implementation have changed and is untested (previous service has been closed since may 2017)

Settings description:

  • provider: "bing" (mandatory)

  • 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

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)

  • DoxyDoxygen: Select Untranslated Messages : doxy_chain_commands(commands=[['view.doxy_select_translatable', OrderedDict([('scope', 'untranslated')])], ['view.clear_bookmarks'], ['view.toggle_bookmark']])

  • DoxyDoxygen: Select All Translatable Messages : doxy_chain_commands(commands=[['view.doxy_select_translatable', OrderedDict([('scope', 'all')])], ['view.clear_bookmarks'], ['view.toggle_bookmark']])

  • 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