Project

General

Profile

Guidelines for API documentation » History » Version 20

« Previous - Version 20/24 (diff) - Next » - Current version
neels, 02/01/2019 02:31 AM


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:

Marker style

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

/*! Item summary.
 * Details follow. */
struct item {
    int member; /*!< Member summary. */
};

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

/*! Brief description (e.g.\ using only a few words). Details follow. */

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.

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

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:

/*! 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)
{
...

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].

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

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 for details.

Files and Groups

Choose distinct names in the '\file' and '\defgroup' directives: 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 or group names in the first place.

Doxygen allows grouping elements: a group can include code elements and also entire files, and join them with a common description and cross references.

Use this pattern:

/*! \file foo.h
 * API to provide Fooing.
 */
/* Copyright...
 */

#include <xyz>

/*! \defgroup fooing  Fooing Listed Name
 * @{
 * \file foo.h
 */

struct foo {
...
};

int foo(struct foo *f);

/*! @} */
/*! \file foo.c
 * Implementation of Fooing.
 */
/* Copyright...
 */

/*! \addtogroup fooing
 *
 * 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;
}

...

/*! @} */

You can reference this group across libraries, for example:

/*! \defgroup fooing_vty
 * VTY for \ref fooing.
 */

Which will render as "VTY for Fooing short description of one sentence."
(if cross referencing between the libraries is set up properly).

Reasons for above pattern:

  • A \file with short description should be the first line of the file.
  • Later on, name the same \file without the short description, after an opening @{ to add to a specific group.
  • Do not add other #include directives within the group braces.
  • A \defgroup initially defines a group, this shall exist only once, preferably in a .h file.
  • More items can be added using an \addtogroup marker. Use this in the .c file and add a long description with references.
  • Put the longer description in the .c file, not the .h 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",
    or "\file foo.h" and "\file vty/foo.h".
  • Be aware, any description following \file will be associated with that file and not the group.
  • If a file's description matches a group's description, don't describe the file at all to avoid duplicated docs.
Add picture from clipboard (Maximum size: 48.8 MB)