Documenting Code for Traceability

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 and input for other tools that is used to generate a reference manual from documented source files.

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 the validate creating a link back to the APIs and by reference to the original requirements.

Guidelines for Documentation

Test Code

Zephyr comes with many test types and methods of testings, the most common test method Ztest. 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.

Test documentation should not interfere with the actual API documentation and need 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 them 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 suffixed with _tests

To establish link with the feature and APIs under test we use the @see directive to link back to APIs and the implementation to be tests.

Example

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

/**
 * @}
 */