Main Page
Doxbar
DoxBar is an add-in for using doxygen from within Developer Studio. The
add-in has three functions:
- It can be used to run doxygen on the sources and header files of
the current project and its dependencies. These are those sources and
header files that are visible from the Workspace under the project
whose name is displayed in bold.
- It can be used to automatically generate comments for common C++
code
- It can be used to open an external help file, by means of a
button or key press, while searching for the current selection, the
word under the cursor, or the current file name.
Copyright © 2000-2002 by Dimitri
van Heesch.
Permission to use, copy, modify, and distribute this software and
its documentation under the terms of the GNU General Public License is
hereby granted. No representations are made about the suitability of
this software for any purpose. It is provided "as is" without express
or implied warranty. See the GNU General Public License
for more details.
The latest release of the add-in can be downloaded in source or binary
form from the doxbar
project page on sourceforge. Development sources can be obtained
from the CVS
repository using doxbar as the module name. This add-in has been
tested under Windows XP Home edition and might not work under other
windows platforms.
To be able to use or compile the add-in, you need the following:
Do the following to install the tool:
- Start developer studio.
- From the "Tools" menu select "Customize...".
- Select the "add-ins and Macro Files" tab.
- Press "Browse" and select files of type "add-ins (.dll)".
- Browse to the location of doxbar.dll and press "open".
- The config menu should now look like this:
- Press "Close".
- A new toolbar should appear:
- From the "Tools" menu select "Customize..." again.
- Select the "Tools" tab and add a new item to the list called
doxygen.
- Set the options as follows:
The batch file after command does not need to exist. It will be
generated by DoxBar. To avoid a warning from developer studio you could
create an empty batch file with that name, but make sure it is
writable. For a convenient output, do not forget to check the Use
Ouptut Window checkbox.
- Press "Close".
- Select the "Tools" menu again and remember the number of the user
tool called doxygen. For a freshly installed developer studio it should
be 6 or 7:
- Press the configure button of the DoxBar add-in (
)
A configuration menu like the following should appear:
- In the "User tool" tab, fill the edit control with
"UserTool<number>", where <number> should be the remembered
number (e.g. 7).
- In the "File locations" tab
- For the "Batch file" fill in the same path and file as you did in
the configure menu.
- Fill in (or browse to) the location of the doxygen executable.
- At the "Configuration template" field you may fill in (or browse
to) a Doxygen configuration file. The settings in this file will be
used as a template for the DoxBar tool. Some options (like INPUT) will
be overwritten. You can run doxygen with the -g option to generate a
template configuration file which you may want to place in a template
subdirectory. If you lieve this field blank, you will be asked if you
want to create one the first time you execute doxbar on the active
project.
- Fill in (or browse to) the location of the HTML help compiler
(this comes with the HTML Help workshop).
- In the "Help invokation" tab, fill in the informations according
to the description done in the Using the
HELP feature section
- In the "Auto comment" tab
Indicate the path to the place of common comment templates. Please
refer to Using the Auto Comment
feature section for details
- Press "Ok". All settings will be stored in the system's registry.
To run doxygen on a project do the following:
- Load the workspace/project
- Make the main project active (right click on the name, and select
"Set as Active Project"). If the main project is not selected or the
workspace name is not the same as your main project's, you will receive
a warning stating that doxbar wasn't able to read the workspace file.
You may choose to continue, but any dependencies will be discarded.
- Press on the Execute button of the DoxBar (
)
- If you left the template field blank during setup, you will be
asked if you want doxbar to create a template for you. You should
answer Yes as this is the easiest way to get a valid project template.
- Doxygen should now start, dumping its output in the Output window
under the doxygen tab. If you set the the profile entry WARN_FORMAT to
'$file($line) : $text' you will be able to double click on a warning
from doxygen to directly navigate to the incriminated file.
- After doxygen has completed the HTML Help compiler will compile a
compressed HTML file of the result (unless you turned off this option).
To start an external help file (for instance one that was generated
with doxygen :-) do the following once:
- Press the configure button of the DoxBar add-in ()
- In the "Help invokation" tab
you see the current selected item (initially CustomHelp1). The current
item is the one that will be executed by pressed the "Search" button of
the add-in (
)
- Fill in (or browse to) the help file that should correspond to
this item. You can use the special strings %PROJECT_PATH% and
%PROJECT_NAME% that will be respectively replaced by the active
project's path and the active project's name (without path nor
extension)
- Select one or more of the lookup boxes. Depending on what you
want. The lookup will be done for all marked items in the order shown.
After that you can just press the "Search" button to lookup the
selection or a word in the index of the help file.
You may wonder why there is more than one help option while there is
only one help button.
This is because all help options are available to developer studio. You
can assign a key to any of them, by selecting "Customize..." from the
Tools menu. Select the "Keyboard" and Category "Add-ins":
Position the caret on the line you want to be automatically commented
and simply press the Auto Comment button (
). Doxbar will analyse the line and will
recognize class, function and typedef declarations. If none of these
three are recognized, a default comment will be added.
In the doxbar and project options, you can indicate a path to
comment templates. If you leave these fields blank, the running
directory will be used. The used path will be searched for the
following files:
- class.txt
- function.txt
- typedef.txt
- default.txt
These files should contain C++ comments with special tags that will
follow these rules:
- In class.txt, %CLASSNAME% will be replaced by the name of the
class
- In function.txt, %FUNCTIONNAME% will be replaced by the name of
the function
- In function.txt, %FUNCTIONTYPE% will be replaced by the type of
the function (the type of the value returned)
- In function.txt, the first line to contain \param or @param will
be repeated for all the parameters with %PARAMTYPE% and %PARAMNAME%
replaced by the type and name of the parameter
- In typedef.txt, %ORIGINALTYPE% and %NEWTYPE% will be replaced by
the original type and the new type being defined
- In default.txt, no special tags will be replaced.
Moreover, in all templates, in every possible line, the following tag
will be recognized
%DATE%=DateFormat=%DATE%
Where DateFormat is a valid format to pass to the strftime() standard
function. Please see at this website for details: MSDN
strftime() page
If one or more of these files is missing, the default templates will be
used
Doxbar will generate a configuration file based on the template you
indicated during setup, or the one generated by doxbar. If you want to
alter the settings of this template click on the template button (
). The following dialog will show up:
If you leave your mouse long enough on a entry zone, you will get, as
on the picture, a tool tip message explaining what is the function of
the zone. This only works if the template doxyfile contains comments.
This is why you should let doxbar create a basic template and copy it
in your project's directory.
All the tabs in this dialog are generated from the template file except
the 'Doxbar specific' tab. This one contains project dependent options,
specific to doxbar and changing the values of these options will not
affect directly the way doxygen generates the documentation.
You can choose how doxbar explores the projects collection in the
current workspace. Selecting 'the active project and its dependencies'
requires that the workspace file (.dsw) is named the same as the active
project file (.dsp). A warning will be issued if this is not the case.
You can also choose to force HTML and HTML Help outputs. It is
recommanded to check those two options to get full use of doxbar.
Please note that the template changes are made on the project's
doxyfile, not on the default template. Moreover, the doxbar specific
settings are stored in a file named after the project's name but with
the .dox extension, created in the project's directory.
If you indicated a file name in the WARN_LOGFILE of the configuration
file, you can use the log button (
) to display
its content in the Macro tab of the Output window.
To allow a convenient navigation from the output window to the source
it is necessary to set the profile entry WARN_FORMAT to '$file($line) :
$text'
However, if you checked the Use Output Window check box during
installation, this may not be really usefull as the generated output is
already available in the Doxygen tab of the output window.
Special thanks go to:
- Dimitri van Heesch for Doxygen and starting this addin
- Mike Copperwhite for providing the help browser part of this
add-in.
- Robert Radtke, Michael Beck and Pekka Pessi for the help leading
to version 0.12
- Bernhard Nowara for creating version 0.14
- Olivier Sannier for restarting development of doxbar
Generated on Fri Nov 21 21:06:21 2003 for
Doxbar by
1.2.18
