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. Test documentation 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 from 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_testsdoxygen groupAll test documentation should be under doxygen groups that are prefixed with tests_
The custom doxygen @verify directive signifies that a test verifies a
requirement:
/**
* @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
*
* @verify{@req{1111}}
*/
void test_sema_thread2thread(void)
{
...
}
...
/**
* @}
*/
To get coverage of how an implementation or a piece of code satisfies a
requirements, we use the satisfy alias in doxygen:
/**
* @brief Give a semaphore.
*
* This routine gives @a sem, unless the semaphore is already at its maximum
* permitted count.
*
* @note Can be called by ISRs.
*
* @param sem Address of the semaphore.
*
* @return N/A
* @satisfy{@req{015}}
*/
__syscall void k_sem_give(struct k_sem *sem);
To generate the matrix, you will first need to build the documentation, specifically you will need to build the doxygen XML output:
$ make doxygen
Parse the generated XML data from doxygen to generate the traceability matrix.