Vicente Hernando's web site

Doxygen is a documentation generator for C, C++, and other programming languages.


How to document the sources:
http://www.doxygen.nl/manual/starting.html#step3

Manual overview:
http://www.doxygen.nl/manual/index.html

Documenting the code:
http://www.doxygen.nl/manual/docblocks.html




You can document most entities with doxygen in two ways:

• Special block near the definition


• Structural commands

Special documentation block near the definition or declaration

Write a special documentation block in front of the definition or declaration of the entity (member, class, namespace, etc)

E.g: Document a function

/**
 * @brief Free an object.
 *
 * @return 0 on success.
 */
static int obj_free(msg_t *msg)

Sometimes is also allowed to write the documentation directly after the member.

E.g:

int start = 0; /**< Start value of counting sequence. Negative values not allowed. */

Learn more about special documentation blocks:
http://www.doxygen.nl/manual/docblocks.html#specialblock



Prior to document a member of a C++ class, namespace or structure, you must also document the class, namespace or structure itself.

You must first document the file that contains a global C function, typedef, enum or preprocessor definition before documenting that function, typedef, etc.

Use a structural command

Write a special documentation block somewhere else (another file or another location). Not near the entity you document.

You need to put a structural command in the documentation block.
http://www.doxygen.nl/manual/docblocks.html#structuralcommands


Using structural commands require to write again the name of the entity being documented.
Writing special blocks near the documented entity is recommended over using structural commands.


Documenting with structural commands is the only available way for @file command (To document a file)

Structural commands:

    @struct to document a C-struct.
    @union to document a union.
    @enum to document an enumeration type.
    @fn to document a function.
    @var to document a variable or typedef or enum value.
    @def to document a #define.
    @typedef to document a type definition.
    @file to document a file.
    @namespace to document a namespace.
    @package to document a Java package.
    @interface to document an IDL interface.

E.g:

Structural commands require to write the name of the entity again. (Here the name of the function)

/** @fn static int obj_free(msg_t *msg)
 * @brief Free an object
 * @return 0 on success
*/

Examples of Doxygen comments

I am going to describe a style to write doxygen comments, but there are other styles too.


Doxygen comments:

Start with /**
End with */

Each intermediate line has 'space * space' but this is optional.

Commands start with @ or \ E.g: @file, @brief, \file, \brief


Special commands:
http://www.doxygen.nl/manual/commands.html

/**
 * @file
 * @ingroup my_group
 * @brief my_group A group created to show in an example.
 *
 */

@brief command adds a short description.


Usually doxygen comments come before the object we want to document:

E.g: before a function:

/**
 * <A short one line description>
 *
 * <Longer description>
 * <May span multiple lines or paragraphs as needed>
 *
 * @param  Description of method's or function's input parameter
 * @param  ...
 * @return Description of the return value
 */

E.g:

/**
 * @brief Looks for the header
 *
 * On error content pointed by s is undefined. (This is part of the
 * detailed description)
 *
 * @param msg - the message
 * @param s  pointer to string where we will store the header.
 *
 * @return 0 on success
 * @return -1 on failure
 */
static int get_header(struct _msg *msg, char *s)

@brief short description.

After the short description may come a detailed description.

@param describes a parameter of the function.

@return describes the return of the function.
Several returns are appended.


If we document this function using a structural command, then we do not need to write the doc before the function, but anywhere else.
Nevertheless writing the doc using structural commands is not recommended.

/**
 * @fn get_header(struct _msg *msg, char *s)
 * @brief Looks for the header
 *
 * On error content pointed by s is undefined. (This is part of the
 * detailed description)
 *
 * @param msg - the message
 * @param s  pointer to string where we will store the header.
 *
 * @return 0 on success
 * @return -1 on failure
 */

Document after a member:

Sometimes is allowed to write documentation after the documented entity by using /**<

E.g:

int start = 0; /**< Start value of counting sequence. */
int end = 0; /**< End value of counting sequence. */

Grouping:

If we want to group some entities.

Create a group:

/**
 * @defgroup my_group This is a group created for this example.
 *
 * This is a detailed description of the new group.
 * It can expand along several lines.
 */

Another way to create a group. This command does not care if the group was already defined.
Then it only appends the description to former definition.

/** @addtogroup my_group
 * @ingroup upper_group
 * @{
 *
 * This is an example of how to define my_group.
 * If already defined it appends this description to the group description.
 */

@ingroup command adds some entity to a group.


Manually indicate start and end of a group:

/** @{ */
 
 Items to group.

 /** @} */

We can assign a name to a group:

/**
 * @name Module parameters
 *
 * @brief Here comes all parameters of the module.
 *
 * @{
 */

 int first_parameter;
 int second_parameter;

 /** @} */

Add a reference to something

@ref creates a reference to a named section, subsection, page or anchor.

E.g: reference to my_group group:

 @ref my_group