toolboxdoxygen.txt              Doxygen Tool                     Feb 14 2016

Doxygen Tool                                                 toolbox-doxygen

                            Plug-in version 0.9.2
                        for Vim version 7.0 and above
                 Wolfgang Mehner <wolfgang-mehner at>

The Doxygen tool integrates Doxygen. After generating a documentation, the
warnings can be displayed in a quickfix list at any time. The tool assists
with generating Doxygen configuration files and with handling other Doxygen-
related files.

0.  TABLE OF CONTENTS                               toolbox-doxygen-contents

 1.    Introduction                               |toolbox-doxygen-intro|
 2.    Commands                                   |toolbox-doxygen-commands|
 2.1    API                                       |toolbox-doxygen-api|
 3.    Configuration                              |toolbox-doxygen-config|
 4.    Troubleshooting - Known Issues             |toolbox-doxygen-issues|

 A.    Change Log                                 |toolbox-doxygen-change-log|

1.  INTRODUCTION                                       toolbox-doxygen-intro

As a first step, the Doxygen configuration file can be set using the ex-
command |:DoxygenConfigFile|:
  :DoxygenConfigFile ./Doxyfile
This file will now be used, independently of the working directory. Now
Doxygen can be run via |:Doxygen|. Afterwards, the warnings are displayed in a
|quickfix| list. They can be shown later using |:DoxygenWarnings|.

A new configuration file can be generated using |:DoxygenGenerateConfig|. The
user is prompted for a location and name of the new config file. This file is
then generated and its name stored as it would be using |:DoxygenConfigFile|.
The file can be conveniently accessed later via |:DoxygenEditConfig|.

The command |:DoxygenWizard| runs doxywizard. If a configuration file is
already set via |:DoxygenConfigFile|, the wizard is started for that project.

Whenever Doxygen is run, the output is written into log files. The output is
split into the |:DoxygenLogFile| and the |:DoxygenWarningFile|. If the option
'WARN_LOGFILE' is set in the Doxygen config file, the name of the warning file
is automatically recognized. Then the quickfix lists generated by |:Doxygen|
and |:DoxygenWarnings| will read the warnings from this file.

All the configured files can be displayed via |:DoxygenRuntime|, which
provides a short overview of the current state of the tool.

  Command                       Short Description
  |:Doxygen| [<args>]             run Doxygen with the given arguments
  |:DoxygenWizard| [<args>]       run doxywizard with the given arguments

  |:DoxygenGenerateConfig|        generate a configuration file
  |:DoxygenEditConfig|            edit the configuration file
  |:DoxygenViewLog|               view the log file
  |:DoxygenWarnings|              |quickfix| list for Doxygen warnings

  |:DoxygenConfigFile| [<file>]   set the configuration file
  |:DoxygenLogFile| [<file>]      set the log file
  |:DoxygenWarningFile| [<file>]  set the warning file

  |:DoxygenRuntime|               shows the runtime information
  |:DoxygenSettings|              shows the plug-in settings
  |:DoxygenHelp|                  help for the Doxygen tool

Detailed explanations are given in the next section |toolbox-doxygen-commands|.

2.  COMMANDS                                        toolbox-doxygen-commands

This chapter provides detailed explanations of all the commands.

  :Doxygen [<args>] 

Runs Doxygen. If called without arguments, uses the config file set via
|:DoxygenConfigFile|. The output produced by Doxygen is written into the log
file (see |:DoxygenViewLog| and |:DoxygenLogFile|) and the warning file (see
|:DoxygenWarnings| and |:DoxygenWarningFile|).
The warnings are then read back from the warning file (see
|:DoxygenWarningFile|) to produce a |quickfix| list. The warnings can also be
viewed later using |:DoxygenWarnings|.
If an warning file is set in the Doxyfile configuration file (option
"WARN_LOGFILE"), it is recognized and used as the warning file.

If the tool is not working properly, prints the reason.

  :DoxygenWizard [<args>] 

Runs doxywizard with the given arguments. If called without arguments, the
wizard is started for the config file set via |:DoxygenConfigFile|. If this
file is not readable, just starts the wizard.

If the tool is not working properly, prints the reason.

  :DoxygenConfigFile [<file>] 

Sets the Doxygen configuration file. If a specific file has been selected, it
is always used, independent of the current working directory. The directory of
the file is used as the working directory for running Doxygen (see |:Doxygen|).


Echoes the current configuration file on the command line.

  :DoxygenLogFile [<file>] 

Sets the Doxygen log file. If a specific file has been selected, it is always
used, independent of the current working directory. The file can be viewed by
calling |:DoxygenViewLog|.


Echoes the current log file on the command line.

  :DoxygenWarningFile [<file>] 

Sets the Doxygen warning file. If a specific file has been selected, it is
always used, independent of the current working directory. The file is used to
read the warnings for |:DoxygenWarnings|.


Echoes the current warning file on the command line.


The user is asked to pick a location and name for a new config file, which is
then generated automatically. Upon successful completion, the name of the
config file is set as it would be using |:DoxygenConfigFile|.


Opens the configuration file set via |:DoxygenConfigFile| for editing.


Views the log file set via |:DoxygenLogFile|.


Reads the warnings from the warning file set via |:DoxygenWarningFile| and
generates a |quickfix| list.


Opens the help for the Doxygen tool.


Shows important runtime information:
- the configured files (config, log, warning)


Shows the plug-in settings. The second version is verbose.

2.1  API                                                 toolbox-doxygen-api

The various filenames can be set via an API. This allows for setting up the
configuration via a script.

The filenames can be set using:

  mmtoolbox#doxygen#Property ( mode, key [, value] ) 

  mode  - "echo", "get" or "set" (string)
  key   - the name of one of the properties (string)
  value - the new value of the property,
          only with mode "set" (string, optional)
  value - the current value of the property,
          only with mode "get" (various)

The property is one of the following:
  "enabled"      - non-zero if the tool is enabled (integer, no "set")
  "config-file"  - the configuration file (string)
  "log-file"     - the log file (string)
  "warning-file" - the warning file (string)

To set the configuration file for a project, use:
  call mmtoolbox#doxygen#Property ( "set",
      \ "config-file", "$HOME/Projects/MyProject/doc/Doxyfile" )

To set the warning file:
  call mmtoolbox#doxygen#Property ( "set", "warning-file",
      \ "$HOME/Projects/MyProject/doc/doxy_warnings.txt" )
This requires the Doxygen configuration file to include the following line:
  WARN_LOGFILE = "doxy_warnings.txt"

3.  CONFIGURATION                                     toolbox-doxygen-config

The tool is configured via a number of global variables, which can be set in
the .vimrc file.

  Variable                  Default       Description and further information
  |g:Doxygen_BinPath|         ''            the path to the binaries (^1)
  |g:Doxygen_Executable|      'doxygen'     the Doxygen executable
  |g:Doxygen_WizardExec|      'doxywizard'  the doxywizard executable

  The Unix defaults are as follows:
  |g:Doxygen_BinPath|         - -empty-
  |g:Doxygen_Executable|      - g:Doxygen_BinPath + doxygen
  |g:Doxygen_WizardExec|      - g:Doxygen_BinPath + doxywizard
  the Windows defaults are as follows:
  |g:Doxygen_BinPath|         - -empty-
  |g:Doxygen_Executable|      - g:Doxygen_BinPath + doxygen.exe
  |g:Doxygen_WizardExec|      - g:Doxygen_BinPath + doxywizard.exe

The path to the executables is set by g:Doxygen_BinPath:
  let g:Doxygen_BinPath = '/usr/local/bin/'
Since doxygen and doxywizard will be on the path, this will not be necessary
on most UNIX systems.

For Windows, set up the binary path similar to this:
  let g:Doxygen_BinPath = 'C:\Program Files\doxygen\bin\'

The defaults for |g:Doxygen_Executable| and |g:Doxygen_WizardExec| are derived
from g:Doxygen_BinPath. However, the setting g:Doxygen_BinPath is only used to
derive the defaults. If one of the executables is set explicitly, it has to be
set with the whole path.

The executable is set by g:Doxygen_Executable:
  let g:Doxygen_Executable = 'doxygen'

The executable of doxywizard is set by g:Doxygen_WizardExec:
  let g:Doxygen_Executable = 'doxywizard'

4.  TROUBLESHOOTING - KNOWN ISSUES                    toolbox-doxygen-issues

* doxygen or doxywizard are not running.
  - Are they executable from the command line?
  - Is the $PATH variable set correctly?
  - Are the settings correct? See:
      :help |toolbox-doxygen-config|
  - Under Windows, make sure the options 'shell', 'shellcmdflag',
    'shellquote', and 'shellxquote' are set correctly. If "cmd.exe" is used as
    the 'shell', 'shellxquote' must be set to a double quote:
      :set shellxquote=\"

A.  CHANGE LOG                                    toolbox-doxygen-change-log


- Add: Command |:DoxygenWizard| and configuration |g:Doxygen_WizardExec|.
- Add: Command |:DoxygenRuntime|.
- Add: Configuration |g:Doxygen_BinPath|.
- Internal changes, less global functions.
- Further internal changes.
- Minor changes.


- Change: Commands :Doxygen and :DoxygenWarnings do not jump to the first
  warning anymore. The old behavior was inappropriate for large projects with
  lots of warnings.
- Minor changes.


- Initial upload.


Generated by vim2html (modified) on So 14. Aug 17:16:25 CEST 2016