Guidelines for API documentation » History » Revision 18
Revision 17 (neels, 02/01/2019 02:09 AM) → Revision 18/25 (neels, 02/01/2019 02:27 AM)
h1. Guidelines for API documentation
Find the current API doc in HTML form here: http://ftp.osmocom.org/api/latest/
We use doxygen for API documentation, for an overview see http://www.doxygen.nl/manual/docblocks.html. Please follow these guidelines:
h2. Marker style
Use the @/*!@ (Qt-style) doxygen markers.
<pre>
/*! Item summary.
* Details follow. */
struct item {
int member; /*!< Member summary. */
};
</pre>
h2. Summary
Since we are using the AUTOBRIEF feature, omit '\brief', and always end the first sentence with a full-stop "." to mark the end of the short description.
To have a dot in a summary, use an escaped space like
<pre>/*! Brief description (e.g.\ using only a few words). Details follow. */</pre>
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. Locations
Header files usually contain merely function declarations bare of any API docs. The API doc comment should be in a @.c@ file at the definition of a function.
Structs and enums defined in a header file, though, also have their API doc comments in that @.h@ file.
Comments for single-line items like enum values or struct members can be placed on the same line using @/*!< Description */@.
h2. Grammar
Always use the imperative form, i.e. omit wording like "This function does", and avoid writing documentation that merely mirrors a function's name. For example:
<pre>
/*! Return a (static) buffer containing a hexdump of the msg.
* \param[in] msg message buffer
* \return a pointer to a static char array
*/
const char *msgb_hexdump(const struct msgb *msg)
{
...
</pre>
h2. Parameters
All parameters of a function should be documented. Input params are documented with @\param[in]@, where out-parameters (pointers to which returned data is written) are documented with @\param[out]@. Rarely, a param is both: @\param[in,out]@.
<pre>
/*! Apply nifty algorithm.
* \param[in] x0 First factor.
* \param[in] n Amount of values to calculate.
* \param[out] buf Write calculated values to this buffer.
*
* Optional longer function description. */
</pre>
It is also possible to document parameters without a direction, using merely @\param param_name Description@, however, it is desirable to always indicate @[in]@, @[out]@ or @[inout]@.
Parameters can *not* be referenced with @\ref@, nor with @\a@. See "this post":https://lists.osmocom.org/pipermail/openbsc/2019-January/012603.html for details.
h2. File comments
Choose distinct names in the '\file' directive: similar names will Doxygen, even if they are in separate subdirs and even separate libraries.
An example is osmocom/code/stats.h vs osmocom/vty/stats.h. If both of these are advertised as '\file stats.h', the duplicate handle will lead to both files missing from their respective groups.
Solutions:
* write '\file core/stats.h' and '\file vty/stats.h'
* do not use identical file names in the first place
Descriptions:
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>
A more detailed description may follow later. Typically though, we place longer descriptions in groups, see below.
<pre>
/*! \file foo.c
* Short description.
*/
/*
* (C) 2017 ...
*/
/*! \file foo.c
*
* More information in multiple lines.
*/
</pre>
If a file needs no description, it is ok to omit the @\file@ tag entirely. Since we are using EXTRACT_ALL = YES, files lacking a @\file@ tag are still listed in the API docs.
h2. Groups
Doxygen allows grouping elements: a group can include code elements and also entire files, files.
This works by enclosing the items to be grouped between an opening and join them with a common description and cross references. closing marker:
Use * A @\defgroup@ initially defines a group, this pattern: shall exist only once.
* More items can be added using an @\addtogroup@ marker.
* Both have to be closed by "@}".
For example:
<pre>
/*! \file foo.h \defgroup groupname Short description of the group.
* API to provide Fooing. @{
*/
struct type_that_belongs_to_group {
...
/* Copyright... };
void func_that_belongs_to_group()
{
...
}
/*! @} */
</pre>
#include <xyz>
and
<pre>
/*! \defgroup fooing Fooing Listed Name \addtogroup groupname
* @{
* \file foo.h
*/
struct foo {
...
};
int foo(struct foo *f);
/*! @} */
</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
* Implementation of Fooing.
File's description. */
/* Copyright...
* (C) ...
*/
/*! \addtogroup fooing groupname
*
* Fooing short description of one sentence.
*
* Fooing has a long description with many applications in modern Foo science.
* Apply the Foo, not to be confused with the Fu, or Kung.
*
* @{
* \file foo.c
*/
int foo(struct foo *f) {
return 0xf00;
}
...
/*! @} */
</pre>
In detail:
* A \file with The point is that we like to have a file's short description should be near the first line start of the file, to also serve us well when we're reading only the .h file.
* Later on, name But to be included in a group, the same \file without doxygen group start must precede the short description, after an opening @{ @\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 to a specific group.
* Do not add other #include directives within second descriptionless @\file@ with the group braces.
* opening.
A \defgroup initially defines group may contain a group, this shall exist only once, preferably short as well as a longer description. We often @\defgroup@ in a .h file.
* More items can be added using an \addtogroup marker. Use this in the .c @.h@ file and add a long description with references.
* Put but keep the longer description in the .c file, not the .h an @\addtogroup@ in a @.c@ file.
* Both have to be closed by "@}".
* Choose distinct group and file names, even across separate libraries, e.g. "\defgroup foo" and "\defgroup foo_VTY",
Any @\file@ tags must follow *after* such description, or "\file foo.h" and "\file vty/foo.h".
* Be aware, any the description following \file will be associated with that the file and not instead of the group:
@.h@ file:
<pre>
/*! \defgroup groupname Short description of the group.
* @{
*/
...
/*! @} */
</pre>
@.c file:
<pre>
/*! \addtogroup groupname
* If @{
* 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, don't describe description. In that case, the file at all file's description header comment can be omitted to avoid duplicated docs. duplicating identical descriptions.
<pre>
/*
* (C) 2017 ...
*/
/* \addtogroup group
* @{
* Description...
*
* \file foo.c */
...
/* @} */
</pre>
