Guidelines for API documentation¶

We use doxygen for API documentation, following these guidelines:

Use the /*! (Qt-style) doxygen markers.

Since we are using the AUTOBRIEF feature, always end the first sentence with a full-stop "." to mark the end of the short description.
This allows omitting the \brief markers everywhere.

Never rely on line breaks as semantic separation or to end a sentence, always use proper punctuation. The API doc may be rendered with different line breaks than in the source file.

File comments¶

If a file contains a descriptive comment, this comment should be right at the start of the file, as a doxygen \file section.
The first sentence must be ended by a full stop "." to mark the end of the short description.
The copyright notice shall not be part of such API doc file comment.

/*! \file foo.c
 * Short description. */
/*
 * (C) 2017 ... Copyright not in a doxygen comment
 * license information
 */

or

/*! \file foo.c
 * Short description.
 *
 * More information in multiple lines.
 */
/*
 * (C) 2017 ...
 */

Groups¶

Doxygen allows grouping elements: a group can include code elements and also entire files.

This works by enclosing the items to be grouped between an opening and a closing marker:

• A \defgroup initially defines a group, this shall exist only once.
• More items can be added using an \addtogroup marker.
• Both have to be closed by "@}".

For example:

/*! \defgroup groupname Short description of the group.
 * @{
 */

struct type_that_belongs_to_group {
 ...
};

void func_that_belongs_to_group()
{
 ...
}

/*! @} */

and

/*! \addtogroup groupname
 * @{
 */

...

/*! @} */

If a file should be added to a group, add a (possibly) second, short descriptionless \file tag to the group start. To clearly mark that the purpose is to add to the group, do so within the same comment block:

/*! \file foo.c
 * File's description. */
/*
 * (C) ...
 */

/*! \addtogroup groupname
 * @{
 * \file foo.c */

...

/*! @} */

The point is that we like to have a file's short description near the start of the file, to also serve us well when we're reading only the .h file. But to be included in a group, the doxygen group start must precede the \file tag. Also, the doxygen group should rather not enclose #include directives, to clearly exclude those from the group. Hence, the best way is to keep the file's actual description at the top of the file, and add a second descriptionless \file with the group opening.

A group may contain a short as well as a longer description. We often \defgroup in a .h file but keep the longer description in an \addtogroup in a .c file. Any \file tags must follow after such description, or the description will be associated with the file instead of the group:

.h file:

/*! \defgroup groupname Short description of the group.
 * @{
 */

...

/*! @} */

@.c file:

/*! \addtogroup groupname
 * @{
 * Longer description of the group.
 * - contains a
 * - bullet list
 * 
 * As well as a 
 *
 *     Code example
 *     block
 *
 * All of which must not be below the directive adding this file to the group:
 *
 * \file foo.c */

[...]

/*! @} */

Often, a file's description matches or is identical with a group's description. In that case, the file's description header comment can be omitted to avoid duplicating identical descriptions.

/*
 * (C) 2017 ...
 */

/* \addtogroup group
 * @{
 * Description...
 *
 * \file foo.c */

...

/* @} */