DOXYGENSUPPORT

doxygensupport.txt            Doxygen Support                 March 5 2011
                                                             doxygen-support
                              Plugin version 2.2
                        for Vim version 7.0 and above
                       Fritz Mehner <mehner.fritz@web.de>

This plugin generates a menu and Ex commands from template files containing
user defined comment templates to be used for source code documentation with
Doxygen. Doxygen itself can also be started.


 0.   CONTENT                                             doxygensupport-toc

 1.   The template file                      |doxygensupport-template-file|
 1.1   Template file comments                |doxygensupport-template-comments|
 1.2   Template file macros                  |doxygensupport-template-macros|
 1.3   Predefined Control Macros             |doxygensupport-control-macros|
 1.4   Doxygen Templates                     |doxygensupport-doxygen-templates|
 2.   The Doxygen menu                       |doxygensupport-menu|
 3.   The Doxygen Ex commands                |doxygensupport-ex-commands|
 4.   Rebuilding menus and Ex commands       |doxygensupport-rebuild|
 5.   The run menu                           |doxygensupport-run|
 5.1   Menu entry 'run doxygen'              |doxygensupport-run|
 5.2   Menu entry 'select working directory' |doxygensupport-working-dir|
 5.3   Menu entry 'select config file'       |doxygensupport-select-config-file|
 5.4   Menu entry 'edit config file'         |doxygensupport-edit-config-file|
 5.5   Menu entry 'generate a config file'   |doxygensupport-configfile|
 5.6   Menu entry 'edit local templates'     |doxygensupport-local-templates|
 5.7   Menu entry 'edit global templates'    |doxygensupport-global-templates|
 5.8   Menu entry 'reread templates'         |doxygensupport-reread-templates|
 5.9   Menu entry 'plugin settings'          |doxygensupport-settings|
 5.10   Run ex commands                      |doxygensupport-run-ex-commands|
 6.   Customization                          |doxygensupport-customization|
 7.   System-wide installation               |doxygensupport-system-wide|

 How to add this help file to Vim's help    |add-local-help|

 * @htmlonly
 * @endhtmlonly
Doxygen is a documentation system for C++, C, Java, Objective-C, IDL and to
some extent PHP, C#, and D (http://www.stack.nl/~dimitri/doxygen/index.html,
and Doxygen manual).
Doxygen allows a variety of styles for special documentation blocks.  There is
also a great number of Doxygen commands which can be combined freely into
comment blocks.  For that reason it makes no sense to code these possibilities
directly into a plugin. Therefor this plugin let you define a  file with
templates for Doxygen documentation blocks. This file will be read when Vim
starts or by an explicit rebuild command. The template file will then be
analyzed and a menu item will be created on the fly for each template found
(gVim). In parallel an Ex command will be generated for each item. For the
console version Vim only the Ex commands are available.


1.  THE TEMPLATE FILE                           doxygensupport-template-file

This plugin comes with template files. These files are examples or suggestions
to allow you a quickstart. Please read more to learn how to write your own
templates.

The main template file (default is $HOME/.vim/plugin/doxygen.templates) can
have three sorts of entries.


1.1  Template file comments                 doxygensupport-template-comments

Lines starting with a '#' are comments.

If a line in a template body starts with a '#' (e.g. a C preprocessor
statement) this character has to be escaped
(|doxygensupport-doxygen-templates|).


1.2  Template file macros                     doxygensupport-template-macros

Macros are optional. The syntax is

 $<macroname>$  = <macroexpansion>

A <macroname> starts with a letter followed by optional letters,  digits or
underscores.
A <macroexpansion> is the text on the right of the equal sign, starting with
the first non-whitespace character after the equal sign and ending with the
last non-whitespace in this line. An example

 $AUTHOR$           "Dr. Fritz Mehner"

There are a few predefined macro names:

 $AUTHOR$
 $AUTHORREF$
 $EMAIL$
 $COMPANY$
 $PROJECT$
 $COPYRIGHTHOLDER$

An <macroexpansion> may contain other macros to be expanded. The recursion is
limited by the expansion algorithm to a depth of 10.  The order of the macro
definitions does not matter. Macro names are case sensitive.

There are a few other predefined macros with fixed meaning (but see also
 |doxygentemplates-date| for date and time representation):

 $DATE$          The preferred date representation for the current locale
                 without the time.
 $YEAR$          The year as a decimal number including the century.
 $TIME$          The preferred time representation for the current locale
                 without the date and the time zone or name or abbreviation.
 $FILE$          The filename without the path.
 $PATH$          The pathname without filename.
 $BASENAME$      Filename without path and suffix.
 $SUFFIX$        The filename extension.

 $sortmenus$     Sorted menus yes/no (see below)
 $includefile$   Include a template file (see below).

REMARKS. Case of letters matters. Do not name a macro 'Id' if you want this to
be expanded by a revision control system.


 PREDEFINED TAGS

 <CURSOR>           The cursor position after insertion of a template
 <SPLIT>            The split point when inserting in visual mode
                    (see|doxygensupport-doxygen-templates|)

A dependent template file can start with its own macro section. There is no
need to have all user defined macros in the master file.
When the first template definition is found (see below) macro definitions are
no longer recognized.



1.3  Predefined Control Macros                 doxygensupport-control-macros

The menu items can be sorted with the macro

 $sortmenus$  = yes

Default is 'no'.

This plugin has an include mechanism. The templates can be split in different
files. These can be included, e.g.

 $includefile$  = doxygen.cpp.templates
 $includefile$  = doxygen.java.templates

Each file will be included only once. The file names may not have a path. The
path is assumed to be the same as for the main templates file (see
|doxygensupport-template-file|).


1.4  Doxygen Templates                      doxygensupport-doxygen-templates

A template definition has the following form:

==<templatename>==[<insert mode>==][comment]
1. template line
2. template line
  ...

It starts with a headline with the syntax shown above followed by a Doxygen
comment. The insert mode part (see below) and the comment part are optional.
Whitespaces between the parts are allowed.  The end of a definition is the
start of a new template definition or the end of the file.

A <templatename> starts with a letter followed by optional letters, digits,
or allowed delimiters. The allowed delimiters are

  ' '     blank
  '-'     minus
  '+'     plus
  '_'     underscore
  ','     comma
  '.'     point

A template can contain empty lines. The number of templates is not limited.
Here an example template enclosed in delimiting comments:

#--------------------------------------------------------------
==brief+detailed==
/**
 *  \brief  <CURSOR>
 *
 *  Detailed description starts here.
 */
#--------------------------------------------------------------


INSERT MODE SPECIFICATION

There are 4 insert modes: 'above', 'append', 'below', 'insert', and 'start'.
The default is 'below' The insert mode specification is optional. A wrong
specification will be replaced by the default.

  above     insert the template before the current line
  append    append the template to the current line
  below     insert the template below the current line
  insert    insert the template at the cursor position
  start     insert the template before the first line of the buffer

Examples:

#--------------------------------------------------------------
==brief-after-member==append==
 /*< \brief <CURSOR> /
#--------------------------------------------------------------

#--------------------------------------------------------------
== brief,detailed ==
/**
 * @brief <CURSOR>
 *
 * Detailed description starts here.
 */
#--------------------------------------------------------------

INSERT. In-text formulas should be put between a pair of @f$  commands.  The
following template will be inserted in the running text. The cursor will be
set inside the construct.

#--------------------------------------------------------------
== formula-in-text == insert ==
 @f$ <CURSOR> @f$
#--------------------------------------------------------------
All templates can have more than one line.

Templates for the visual mode can use <SPLIT>. The text before <SPLIT> will
than be inserted above/before the marked area, the text after <SPLIT> will be
inserted below/behind the marked area. An example:

#--------------------------------------------------------------
== formula-in-text == insert ==
 @f$ <CURSOR><SPLIT> @f$
#--------------------------------------------------------------

Templates not containing <SPLIT> do not have a visual mode.



USER INPUT

If the usage of a yet undefined user macro starts with a question mark the
user will be asked for the replacement first, e.g. with the following template

  == Cpp.class ==
  ///
  /// @class $?CLASSNAME$
  /// @brief <CURSOR>
  ///
  /// Description of class $CLASSNAME$ starts here.
  ///

The user can specify the function name which then will be applied twice. If the
macro was already in use the old value will be suggested as default.


MACRO MANIPULATION

A macro expansion can be controlled by the following attributes

  :l    change macro text to lowercase
  :u    change macro text to uppercase
  :c    capitalize macro text
  :L    legalize name

Legalization means:
 - replace all whitespaces by underscores
 - replace all non-word characters by underscores
 - replace '+' and '-' by underscore

EXAMPLE. To ask for a class name and to make sure that it will start with an uppercase
letter write

  == Cpp.class ==
  ///
  /// @class $?CLASSNAME:c$
  /// @brief <CURSOR>
  ///
  ///


HINT. According to the syntax of the headline the 'append' followed by '==' in
the line

==brief-after-member==append==

is an insert mode specification. The 'append' in

==brief-after-member==append

is a comment. The insert mode is now 'below'.



2.  THE DOXYGEN MENU                                     doxygensupport-menu

The Doxygen menu will be generated when the editor starts (GUI only) or on
demand (see|doxygensupport-rebuild|).

The template names from the template definition file become menu items linked
with the template body. The template body will be inserted below the cursor.

The delimiter '.' has a special meaning: it separates a submenu name from its
submenu items. The template names

 ==block.short==
 ==block.long==
 ==block.special==

will generate a submenu entry 'block'  with the items 'short', 'long', and
'special' :

 block --+--> long
         |
         +--> short
         |
         +--> special

This feature can be used to arrange the templates into groups. The template
names

 ==C.block-short==
 ==C.block-long==
 ==C.block-special==
 ==Cpp.block-short==
 ==Cpp.block-long==
 ==Cpp.block-special==

result in menus in which the templates are arranged according to C/C++
commenting styles:

 C   --+--> block-short
       +--> block-long
       +--> block-special
 Cpp --+--> block-short
       +--> block-long
       +--> block-special

The first group will be reached by Ex commands beginning with 'DoxyC' the
second group by 'DoxyCpp' (see below).


3.  THE DOXYGEN EX COMMANDS                       doxygensupport-ex-commands

This plugin generates an Ex command for each Doxygen template.  These commands
will be generated when the editor starts or on demand (see|doxygensupport-rebuild|).

Vim Ex command names have to start always with an uppercase letter followed by
letters or digits. Delimiters are not allowed.  The user defined template
names are therefore transformed into camel case notation.  The parts separated
by the delimiters are joined together now. The first letter of each part will
be transformed to uppercase. The new word will be prefixed by 'Doxy'. Some
examples:

 template name           Ex command

 ==block.long==          DoxyBlockLong
 ==block.short==         DoxyBlockShort
 ==block.special==       DoxyBlockSpecial
 ==file-header==         DoxyFileHeader
 ==function==            DoxyFunction

 ***  You do not need to remember the names of these Ex commands. Just type
 ***  'Doxy' on the command line and use the tab expansion to show the names
 ***  and to choose from.

NAMING CONFLICTS. The template names

 ==block-special==       DoxyBlockSpecial
 ==block+special==       DoxyBlockSpecial

will generate two different menu items but obviously the same Ex command name.
Avoiding these conflicts is up to you.

The Ex command leader can be changed (see|doxygensupport-customization|).


4.  REBUILD MENUS AND EX COMMANDS                     doxygensupport-rebuild

Rebuilding the menu(s) and the Ex commands is necessary after changing the
template file.
Local  template files: see |doxygensupport-template-file|
Global template files: see |doxygensupport-system-wide|

GUI (gVim or Vim in an xterm)

Edit the template file. Choosing the first menu item will reread the template
files and rebuild the menu and the Ex commands.

Console (Vim)

Using the command ':Doxygen' will reread the template files and rebuild the Ex
commands.


5.  THE RUN MENU                                          doxygensupport-run

The run menu let you generate the doxygen documentation. Doxygen has a lot of
options. This plugin needs a doxygen config file. The best way to use it is
probably to generate a doxygen config file in the directory containing the
sources you want to document (see|doxygensupport-configfile|) and to adapt it
to your needs.

5.1  Menu entry 'run doxygen'

If no other information is given (working directory, config file) doxygen will
try to build a documentation in the current directory. If a config file with
the default name 'Doxyfile' is present it will be used otherwise you will be
asked for a config file.

5.2  Menu entry 'select working directory'        doxygensupport-working-dir

Select the directory in which to run doxygen. This is convenient if you are
working in a subdirectory at the moment.
The entry 'plugin settings' shows the currently selected directory.

5.3  Menu entry 'select config file'       doxygensupport-select-config-file

Select a config file if you use one with a non-standard name.  The working
directory will be set to the directory containing this config file.

5.4  Menu entry 'edit config file'           doxygensupport-edit-config-file

Edit the selected config file. start a file browser if file 'Doxyfile' is not
present or no other config file was specified.

5.5  Menu entry 'generate a config file'           doxygensupport-configfile

The menu entry 'generate a config file' starts a file browser and suggests the
default config file name 'Doxyfile'. The config file can have any name. The
file with the given name will then be generated by doxygen. The config files
are well documented but you may want to read the doxygen documentation too.

5.6  Menu entry 'edit local templates'        doxygensupport-local-templates

The menu item 'edit local templates' opens a file browser for the directory
containing the template files of a local plugin installation. This is usually
'~/.vim/doxygen-support/templates/'. Now change whatever file you want, save
it, and click on the run menu item 'reread templates' to read in the file(s)
and to rebuild the internal representation of the templates.

5.7  Menu entry 'edit global templates'      doxygensupport-global-templates

The menu item 'edit global templates' opens a file browser for the directory
containing the template files of a global plugin installation. This is usually
'$VIM./vimfiles/doxygen-support/templates/'. Now change whatever file you
want, save it, and click on the run menu item 'reread templates' to read in
the file(s) and to rebuild the internal representation of the templates.

5.8  Menu entry 'reread templates'           doxygensupport-reread-templates

Read the template files (after a change or addition) and build a new inner
representation of the templates.

5.9  Menu entry 'plugin settings'                    doxygensupport-settings

This menu entry shows the actual settings for the plugin. Some of them can
change during a session (e.g. current the current working directory).

5.10  Run ex commands                         doxygensupport-run-ex-commands

To allow the usage of the functions of the run menu within Vim (without GUI)
the following ex commands are available:

 DxRun
 DxSelectWorkingDir
 DxSelectConfigFile
 DxEditConfigFile
 DxGenerateConfigFile
 DxEditLocalTemplates
 DxEditGlobalTemplates
 DxReread
 DxSettings

These commands start with 'Dx' to separate the names from the commands
generated for the templates. Start with ':Dx' on the Vim commandline and use
tab completion to avoid typing (and remembering the command name).



6.  CUSTOMIZATION                               doxygensupport-customization

Several global variables are checked by the script to customize it:


global variable                    default value

let g:Doxy_ExCommandLeader         'Doxy'
let g:Doxy_LoadMenus               'yes'
let g:Doxy_RootMenu                'Do&xy.'
let g:Doxy_TemplateOverwrittenMsg  'no'

The variable g:Doxy_ExCommandLeader can be used to change the default name of
the Ex command leader (see|doxygensupport-ex-commands|).  The string must
start with an uppercase letter and can contain only letters and digits.
Everything else will be removed.

The variable g:Doxy_LoadMenus controls if the Vim root menu item 'Doxy' will
appear after start. When set to 'no' the menu item can be made visible from
the 'tool' menu.

The variable g:Doxy_RootMenu, if set (in .vimrc or in .gvimrc), gives the name
of the single gVim root menu entry.  The default is 'Do&xy.' . Note the
terminating dot. An empty string is not allowed. The next character after & is
the shortcut key for this menu.

If you want to set the plugin menu into another menu, e.g. 'Plugin', this is
done by the following line in '.vimrc'

  let g:Doxy_RootMenu = "&Plugin.Do&xy."

If the variable g:Doxy_TemplateOverwrittenMsg is set to 'yes' all templates
overwriten by a rebuild will be reported.

There are more global variables for special purposes:
- see |doxygensupport-system-wide|
- see |doxygentemplates-date|


 USER DEFINED FORMATS FOR DATE AND TIME               doxygentemplates-date

The format for $DATE$ ,$TIME$ , and$YEAR$ can be set by the user. The
defaults are
    $DATE$        '%x'
    $TIME$        '%X'
    $YEAR$        '%Y'
See the manual page of the C function strftime() for the format.  The accepted
format depends on your system, thus this is not portable!  The maximum length
of the result is 80 characters.

User defined formats can be set using the following global variables in
~/.vimrc ,  e.g.
    let g:Doxy_FormatDate            = '%D'
    let g:Doxy_FormatTime            = '%H:%M'
    let g:Doxy_FormatYear            = 'year %Y'


7. System-wide installation                       doxygensupport-system-wide

A system-wide installation (one installation for all users) is done as
follows.

As *** SUPERUSER *** :

(1) Find the Vim installation directory.
The Vim Ex command ':echo $VIM' gives '/usr/local/share/vim' or something like
that. Beyond this directory you will find the Vim installation,  e.g. in
'/usr/local/share/vim/vim73' if Vim version 7.3 has been installed
(Windows: 'C:\Program Files\Vim').

(2) Create a new subdirectory 'vimfiles', e.g. '/usr/local/share/vim/vimfiles'
(Windows: 'C:\Program Files\Vim\vimfiles').

(3) Install Doxygen Support
Copy the archive doxygen-support.zip to this new directory and unpack it:
  unzip doxygen-support.zip

(4) Generate the help tags:
  :helptags $VIM/vimfiles/doc

SPECIAL CASES. Some Linux distributions use non-standard names for Vim
directories. SUSE has a directory '/usr/share/vim/site' to put plugins in.
These directories will not be found automatically.  After installing the
plugin below '/usr/share/vim/site' the use of the templates will be enabled by
the following line in '~/.vimrc':

  let g:Doxy_GlobalTemplateFile = '/usr/share/vim/site/doxygen-support/templates/doxygen.templates'

As *** USER *** :

Create your private snippet directory:

  mkdir --parents  ~/.vim/doxygen-support/codesnippets

You may want to copy the snippets coming with this plugin (in
$VIM/vimfiles/doxygen-support/codesnippets) into the new directory or to set a
link to the global directory.

Create your private template directory:

  mkdir --parents  ~/.vim/doxygen-support/templates

Create a private template file 'doxygen.templates' (compulsory) in this
directory to overwrite some macros, e.g.

 $AUTHOR$    = your name
 $AUTHORREF$ = ...
 $EMAIL$     = ...
 $COMPANY$   = ...
 $COPYRIGHT$ = ...

You can also have local templates which overwrite the global ones. To suppress
the messages in this case set a global variable in '~/.vimrc' (Windows:
'~\_vimrc') :

  let g:Doxy_TemplateOverwrittenMsg= 'no'

The default is 'yes'.


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

Generated by vim2html on Sa 5. Mär 10:27:43 CET 2011