Guidelines for API documentation » History » Revision 3
Revision 2 (neels, 06/20/2017 01:58 AM) → Revision 3/25 (neels, 06/20/2017 01:59 AM)
h1. 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.
h2. 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.
<pre>
/*! \file foo.c
* Short description. */
/*
* (C) 2017 ... Copyright not in a doxygen comment
* license information
*/
</pre>
or
<pre>
/*! \file foo.c
* Short description.
*
* More information in multiple lines.
*/
/*
* (C) 2017 ...
*/
</pre>
h2. 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:
<pre>
/*! \defgroup groupname Short description of the group.
* @{
*/
struct type_that_belongs_to_group {
...
};
void func_that_belongs_to_group()
{
...
}
/*! @} */
</pre>
and
<pre>
/*! \addtogroup groupname
* @{
*/
... [...]
/*! @} */
</pre>
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:
<pre>
/*! \file foo.c
* File's description. */
/*
* (C) ...
*/
/*! \addtogroup groupname
* @{
* \file foo.c */
...
/*! @} */
</pre>
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:
<pre>
/*! \defgroup groupname Short description of the group.
* @{
*/
...
/*! @} */
</pre>
@.c file:
<pre>
/*! \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 */
[...]
/*! @} */
</pre>
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.
<pre>
/*
* (C) 2017 ...
*/
/* \addtogroup group
* @{
* Description...
*
* \file foo.c */
...
/* @} */
</pre>
