Doxygen standards

Doxygen standards

All public C API must be documented with Doxygen.

List of commands:

https://www.stack.nl/~dimitri/doxygen/manual/commands.html

Doxygen supports many ways to write docs, so we'll try to follow some standards for our project, exemplified below

Functions

Structs and enums

Fields can be documented inline or above.

Groups

/**
 * @defgroup GPIO GPIO
 * @ingroup IO
 *
 * GPIO (General Purpose Input/Output) API for Soletta.
 *
 * @{
 */

Root groups must be added to our mainpage list at src/lib/common/include/sol-mainloop.h

E.g.:

/**
 * @mainpage Soletta Project Documentation
 *
 * [...]
 * For a better reference, check the following groups:
 * @li @ref Comms
 * @li @ref Datatypes
 * @li @ref Flow
 * @li @ref IO
 * [...]
 */

Files

/**
 * @file
 * @brief These routines are used for GPIO access under Soletta.
 */

Lists and references

* SML is divided in the following groups:
*
* @li @ref Engine
* @li @ref Fuzzy_Engine
* @li @ref Log
* @li @ref Mainloop
* @li @ref Ann_Engine
* @li @ref Variables

Code snippet

* Choosing engines and creating variables is straight-forward after
* [...]
*
* @dontinclude example_doc.c
* @skip main
* @until sml_set_output_state_changed_callback
*
* Terms are a way to split the values in the range in meaningful parts.
* [...]
*
* @until }