*toolboxdoxygen.txt*              Doxygen Tool                     Dec 28 2013

Doxygen Tool                                                 *toolbox-doxygen*

                            Plug-in version 0.9.1
                        for Vim version 7.0 and above
                 Wolfgang Mehner <wolfgang-mehner at web.de>

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|

 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|.

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.

  Command                       Short Description
 ----------------------------------------------------------------------------
  |:Doxygen| [<args>]             run Doxygen 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

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

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*
  :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.

------------------------------------------------------------------------------
                                                          *:DoxygenConfigFile*
  :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|).

  :DoxygenConfigFile! ~

Echoes the current configuration file on the command line.

------------------------------------------------------------------------------
                                                             *:DoxygenLogFile*
  :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|.

  :DoxygenLogFile! ~

Echoes the current log file on the command line.

------------------------------------------------------------------------------
                                                         *:DoxygenWarningFile*
  :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|.

  :DoxygenWarningFile! ~

Echoes the current warning file on the command line.

------------------------------------------------------------------------------
                                                      *:DoxygenGenerateConfig*
  :DoxygenGenerateConfig ~

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|.

------------------------------------------------------------------------------
                                                          *:DoxygenEditConfig*
  :DoxygenEditConfig ~

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

------------------------------------------------------------------------------
                                                             *:DoxygenViewLog*
  :DoxygenViewLog ~

Views the log file set via |:DoxygenLogFile|.

------------------------------------------------------------------------------
                                                            *:DoxygenWarnings*
  :DoxygenWarnings ~

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

------------------------------------------------------------------------------
                                                                *:DoxygenHelp*
  :DoxygenHelp ~

Opens the help for the Doxygen tool.

------------------------------------------------------------------------------
                                                            *:DoxygenSettings*
  :DoxygenSettings ~
  :DoxygenSettings! ~

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.

------------------------------------------------------------------------------
                                                *mmtoolbox#doxygen#Property()*
The filenames can be set using:

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

Parameters:
  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)
Returns:
  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_Executable|      'doxygen'     the Doxygen executable
 ----------------------------------------------------------------------------

------------------------------------------------------------------------------
                                                        *g:Doxygen_Executable*
The executable is set by g:Doxygen_Executable: >
  let g:Doxygen_Executable = 'doxygen'
<
==============================================================================
A.  CHANGE LOG                                    *toolbox-doxygen-change-log*
==============================================================================

------------------------------------------------------------------------------
  RELEASE NOTES FOR VERSION 0.9.1
------------------------------------------------------------------------------

- 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.

------------------------------------------------------------------------------
  RELEASE NOTES FOR VERSION 0.9
------------------------------------------------------------------------------

- Initial upload.

==============================================================================
vim:tw=78:noet:ts=2:ft=help:norl:expandtab:
