Documentation Guidelines

Using Doxygen

Doxygen is a document generation program, used by many C/C++ projects. Its home page is at http://www.doxygen.org. The Sofia documentation is written using Doxygen.

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[in]  k        pointer to a candometer
 * @param[in]  level    orching level
 * @param[out] return_hearping return value for schaduled hearping
 *
 * @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_hearping.
 */
int orch(cando_t *k, int level, hearping_t *return_hearping)
{
  ...
}

The doxygen options are specified through a configuration file, Doxyfile. As a convention, a module-specific Doxyfile includes a common file libsofia-sip-ua/docs/Doxyfile.conf. This makes it possible to keep the module-specific Doxyfiles as clean as possible:

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.

Module documentation in <module>.docs

Each module contains a documentation file containing at least the module mainpage called <module>.docs. There should be the module boilerplate information, for instance the following example is excerpt contents of file ipt.docs:

/**
@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 
- ...
- ...
*/

Common Doxygen Commands

In this section we go through the most common Doxygen commands. All the commands are explained in the manual. The commands include

Style Commands - @a, @b, @c, @e

The text style can be changed with @b (bold), @c (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.

Function Parameters and Return Values - @param, @return, @retval

Parameters to a function are documented with @param commands. (See the orch() function above.) As a convention, the data flow direction [in], [out] or [in,out] is indicated in the brackets after the @param command keyword.

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[in] h pointer to hearping
 * 
 * @retval 0  hearping was successful
 * @retval -1 an error occurred
 */
int schadule(hearping_t *h)
{
  ...
}

Example Blocks - @code, @endcode

An example code fragment can be included using @code and @endcode commands.

/**Destroy a hearping.
 * 
 * The function hearping_destroy() deinitializes a hearping and
 * reclaims the memory allocated for it. 
 * 
 * @param[in,out] h pointer to pointer to hearping
 * 
 * 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)
{

Paragraphs

The command @par can be used to divide text into paragraphs. The text on the same line with @par is used as a subtitle for the paragraph. The commands @date, @note, @bug, @todo, @sa (See Also) and @deprecated can be used to add common paragraphs to documentation entries.

Documenting Files

In most files there is documentation entry for the file itself. It is usually at top after the LGPL reference, containing @file command or alias @CFILE/@IFILE. There are Emacs macros for creating the boilerplate entry.

Grouping Entries

When the structure of the documentation does not follow directory or file structure, it is possible to use grouping commands @defgroup and @ingroup. The command @defgroup creates a group, and @ingroup adds an entry to an group.

Creating Links

Normally, Doxygen creates links to classes (and C structs) when it encounters the struct/class name. It is also possible to add links to functions, type names and variables. If the function name is followed by pair of parenthesis (), Doxygen creates a link to it. If a type name or variable is prefixed with hash #, Doxygen creates a link to it.

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.

Writing Body Text

The main body of the documentation is specified with @mainpage command. The contents of the @mainpage entry become the HTML home page of the documentation set. In each documentation set generated with Doxygen there can be only one @mainpage command. Commands @section, @subsection, and @subsubsection can be used to structure the body text.

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.

Adding Images

Images are added with @image command. As the different documentation formats support different image formats, the @image has list the image file name for each supported documentation format. The following example uses bitmap image for HTML documentation and Encapsulate PostScript for print documents:

@image html sip-parser.gif

@image latex sip-parser.eps