Code Documentation

API Documentation

Well documented APIs enhance the experience for developers and are an essential requirement for defining an API’s success. Doxygen is a general purpose documentation tool that the zephyr project uses for documenting APIs. It generates either an on-line documentation browser (in HTML) and/or provides input for other tools that is used to generate a reference manual from documented source files. In particular, doxygen’s XML output is used as an input when producing the Zephyr project’s online documentation.

Reference to Requirements

APIs for the most part document the implementation of requirements or advertised features and can be traced back to features. We use the API documentation as the main interface to trace implementation back to documented features. This is done using custom _doxygen_ tags that reference requirements maintained somewhere else in a requirement catalogue.

Test Documentation

To help understand what each test does and which functionality it tests we also document all test code using the same tools and in the same context and generate documentation for all unit and integration tests maintained in the same environment. Tests are documented using references to the APIs or functionality they validate by creating a link back to the APIs and by adding a reference to the original requirements.

Documentation Guidelines

Test Code

The Zephyr project uses several test methodologies, the most common being the Ztest framework. The documentation of tests should only be done on the entry test functions (usually prefixed with test_) and those that are called directly by the Ztest framework. Those tests are going to appear in test reports and using their name and identifier is the best way to identify them and trace back to them to requirements.

Test documentation should not interfere with the actual API documentation and needs to follow a new structure to avoid confusion. Using a consistent naming scheme and following a well-defined structure we will be able to group this documentation in its own module and identify it uniquely when parsing test data for traceability reports. Here are a few guidelines to be followed:

  • All test code documentation should be grouped under the all_tests doxygen group
  • All test documentation should be under doxygen groups that are prefixed with tests_

The doxygen @see directive is used to link features and APIs under test, like so:

/**
* @brief Tests for the Semaphore kernel object
* @defgroup kernel_semaphore_tests Semaphore
* @ingroup all_tests
* @{
*/

...
/**
* @brief A brief description of the tests
* Some details about the test
* more details
*
* @see k_sem_init(), #K_SEM_DEFINE(x)
*/
void test_sema_thread2thread(void)
{
...
}
...

/**
* @}
*/