After generating output in either the doxygen or simple-doxygen formats you will then want to include the output into your doxygen project so that the generated API documentation includes information about exceptions. This will usually be done for libraries and not so often for end applications.
For the following examples we will use two different files:
<edoc-project>/src/libs.dox
This is the generated output documentation file for libEDoc.
<example-project>/src/libs/libs.dox
This is the generated output documentation file for all the libraries in the example project. You can see information about generating this file in section: Completing the example project
Currently it is important to use the patched doxygen that comes
with EDoc++. Using the patched version is necessary for the moment,
however in a future release of EDoc++ it is hoped that this patched
doxygen can be removed and that it will work fine with the standard
doxygen distribution. So in order to set the environment to use the
patched doxygen run the edoc_start.sh
script.
The doxygen configuration file usually contains a lot of details about how you want the resulting documentation to look, what output formats to use etc. To include the EDoc++ data into the doxygen config file it is simply a matter of editing the doxygen config files: INPUT parameter. As an example following is a small section of a doxygen configuration file:
...
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
INPUT = $(SRCDIR)
FILE_PATTERNS = *.c *.h *.cpp
RECURSIVE = YES
EXCLUDE = $(SRCDIR)/apps \
$(SRCDIR)/plugins
EXCLUDE_SYMLINKS = NO
...This configuration file is searching in
$(SRCDIR) for all files with extensions .c, .h
and .cpp to obtain the doxygen information. We want to also add the
file: $(SRCDIR)/libs/libs.dox However we need to
ENSURE THAT IT IS THE LAST FILE PROCESSED BY
DOXYGEN. This is because it appends exception documentation
to existing doxygen documentation that may already exist for the
project and the order for the current patched doxygen is important. So
it is NOT possible to just change the FILE_PATTERNS variable to
include *.dox Instead we need to add our .dox file explicitly. Doing
this we would end up with the following:
...
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
INPUT = $(SRCDIR) \
$(SRCDIR)/libs/libs.dox
FILE_PATTERNS = *.c *.h *.cpp
RECURSIVE = YES
EXCLUDE = $(SRCDIR)/apps \
$(SRCDIR)/plugins
EXCLUDE_SYMLINKS = NO
...That is all there is to it. This should now insert the EDoc++ data into the resulting documentation. For examples of what this documentation looks like, browse through the libEDoc API documentation.
When looking through the documentation, you will see that all functions have a line like:
Note: EDoc++ data included
If this line is missing for a particular function then it means
that EDoc++ failed to document that function. You can not be sure of
the exceptions that it throws. This is often caused by problems with
the EDoc++ to Doxygen interface. You may notice that while running
doxygen, there are a number of warnings that appear. This is a problem
that will hopefully be fixed by release 1.0 of EDoc++ but for now it
is possible to fix these problems using suppressions to rename the
functions DeclaredNames. I will not go into detail about that here for
now though. If you want to see an example see the
<edoc-project>/src/libs.eds file.