doc: document how we implement traceability
Change the documentation to cover new aliases and how we support traceability using doxygen. Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
parent
7c055c8cf5
commit
588684654a
1 changed files with 33 additions and 7 deletions
|
@ -38,14 +38,14 @@ Documentation Guidelines
|
|||
*************************
|
||||
|
||||
Test Code
|
||||
**********
|
||||
=========
|
||||
|
||||
The Zephyr project uses several test methodologies, the most common being the
|
||||
:ref:`Ztest framework <test-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 to requirements.
|
||||
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
|
||||
|
@ -58,9 +58,8 @@ for traceability reports. Here are a few guidelines to be followed:
|
|||
- 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::
|
||||
|
||||
The custom doxygen ``@verify`` directive signifies that a test verifies a
|
||||
requirement::
|
||||
|
||||
/**
|
||||
* @brief Tests for the Semaphore kernel object
|
||||
|
@ -75,7 +74,7 @@ like so::
|
|||
* Some details about the test
|
||||
* more details
|
||||
*
|
||||
* @see k_sem_init(), #K_SEM_DEFINE(x)
|
||||
* @verify{@req{1111}}
|
||||
*/
|
||||
void test_sema_thread2thread(void)
|
||||
{
|
||||
|
@ -86,3 +85,30 @@ like so::
|
|||
/**
|
||||
* @}
|
||||
*/
|
||||
|
||||
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.
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue