Doxygen works by extracting the documentation data both from the actual C/C++ source code and from the specially formatted comments. The comments can contain some Javadoc-like special commands.
In general the the style of the comments and documentation should follow the javadoc style guide.
A Doxygen comment must either contain reference about the entity it is describing, e.g., command @file when describing files:
/** * @file foo.c * * Implementation of foo. The foo takes care of grokking xyzzy. * * @author Jaska Jokunen <jaska.jokunen@company-email.address.hidden> \n * * @date Created: Wed Oct 20 15:06:51 EEST 2004 jasjoku */
Usually the entity that is documented comes straight after the documentation comment. For example, documenting a function happens like this:
/** * Orches a candometer. If orching candometer is not possible, it * tries to schadule hearping. * * @param k pointer to a candometer [IN] * @param level orching level [IN] * @param return_h return value for schaduled hearping [OUT] * * @return * The function orch() returns the candometer value, or #ERROR upon an error. * If the returned value is 0, the newly schaduled hearping is returned in * @a return_h. */ int orch(cando_t *k, int level, hearping_t *return_h) { ... }
PROJECT_NAME = "ipt"
OUTPUT_DIRECTORY = ../docs/ipt
INPUT = ipt.docs .
@INCLUDE = ../Doxyfile.conf
TAGFILES += ../docs/docs/doxytags=../docs
TAGFILES += ../docs/su/doxytags=../su
GENERATE_TAGFILE = ../docs/ipt/doxytags
From the file above, you can observe some conventions. The Doxygen-generated HTML documentation is collected in docs subdirectory at top level. A separate output directory is created for each submodule under it. Doxytags for the module are generated in the doxytags file in the output directory.
/** @MODULEPAGE "ipt" - Utility Module @section ipt_meta Module Meta Information Utility library for IP Telephony applications. @CONTACT Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden> @STATUS @SofiaSIP Core library @LICENSE LGPL @section ipt_overview Overview This module contain some routines useful for IPT applications, like - ... - ... */
(code), or @e (italic) commands. Function argument names use style command @a.
For example, a sentence "The Content-Type header ct specifies the media-type of the message body, e.g., audio/amr
would be AMR-encoded audio." is produced with commands like
The @b Content-Type header @a ct specifies the @e media-type of the message body, e.g., @c audio/amr would be AMR-encoded audio.
The style commands have synonyms, e.g., @em and @e mean same, as well as @c and @p.
Return values can be documented in two alternative manners, either using @return command (see orch()) or @retval command. The latter is used if the function returns a small number of possible values, e.g., enumeration or success/failure indication.
/**Schadule hearping. * * The function schadule() schadules a hearping. * * @param h pointer to hearping [IN] * * @retval 0 hearping was successful * @retval -1 an error occurred */ int schadule(hearping_t *h) { ... }
/**Destroy a hearping. * * The function hearping_destroy() deinitializes a hearping and * reclaims the memory allocated for it. * * @param h pointer to pointer to hearping [IN/OUT] * * The function clears the pointer to hearping, so it must be called * with a pointer to pointer: * @code * hearping_destroy(&x->hearping); * @endcode */ void hearping_destroy(hearping_t **h) {
It is also possible to create links with freely selected link to documentation entries with @link and @endlink commands.
When the link target is a named page, section, or subsection, it is possible to use the @ref command.
It is also possible to add individual HTML pages to the documentation. It happens with @page command. These individual pages are like the home page added with @mainpage, they can be accessed with the Related Pages link from the navigation bar.
@image html sip-parser.gif @image latex sip-parser.eps