Cellular Network Infrastructure

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, and join them with a common description and cross references.

Use this pattern:

<pre>

/*! \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);

/*! @} */

</pre>

<pre>

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

}

...

/*! @} */

</pre>

In detail:

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