Cellular Network Infrastructure

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>