1.. _code-documentation:
2
3Code Documentation
4###################
5
6API Documentation
7******************
8
9Well documented APIs enhance the experience for developers and are an essential
10requirement for defining an API's success. Doxygen is a general purpose
11documentation tool that the zephyr project uses for documenting APIs. It
12generates either an on-line documentation browser (in HTML) and/or provides
13input for other tools that is used to generate a reference manual from
14documented source files. In particular, doxygen's XML output is used as an input
15when producing the Zephyr project's online documentation.
16
17Reference to Requirements
18**************************
19
20APIs for the most part document the implementation of requirements or advertised
21features and can be traced back to features. We use the API documentation as the
22main interface to trace implementation back to documented features. This is done
23using custom _doxygen_ tags that reference requirements maintained somewhere
24else in a requirement catalogue.
25
26Test Documentation
27*******************
28
29To help understand what each test does and which functionality it tests we also
30document all test code using the same tools and in the same context and generate
31documentation for all unit and integration tests maintained in the same
32environment. Tests are documented using references to the APIs or functionality
33they validate by creating a link back to the APIs and by adding a reference to
34the original requirements.
35
36
37Documentation Guidelines
38*************************
39
40Test Code
41=========
42
43The Zephyr project uses several test methodologies, the most common being the
44:ref:`Ztest framework <test-framework>`. Test documentation should only be done
45on the entry test functions (usually prefixed with test\_) and those that are
46called directly by the Ztest framework. Those tests are going to appear in test
47reports and using their name and identifier is the best way to identify them
48and trace back to them from requirements.
49
50Test documentation should not interfere with the actual API documentation and
51needs to follow a new structure to avoid confusion. Using a consistent naming
52scheme and following a well-defined structure we will be able to group this
53documentation in its own module and identify it uniquely when parsing test data
54for traceability reports. Here are a few guidelines to be followed:
55
56- All test code documentation should be grouped under the ``all_tests`` doxygen
57  group
58- All test documentation should be under doxygen groups that are prefixed
59  with tests\_
60
61The custom doxygen ``@verify`` directive signifies that a test verifies a
62requirement::
63
64    /**
65    * @brief Tests for the Semaphore kernel object
66    * @defgroup kernel_semaphore_tests Semaphore
67    * @ingroup all_tests
68    * @{
69    */
70
71    ...
72    /**
73    * @brief A brief description of the tests
74    * Some details about the test
75    * more details
76    *
77    * @verify{@req{1111}}
78    */
79    void test_sema_thread2thread(void)
80    {
81    ...
82    }
83    ...
84
85    /**
86    * @}
87    */
88
89To get coverage of how an implementation or a piece of code satisfies a
90requirements, we use the ``satisfy`` alias in doxygen::
91
92    /**
93    * @brief Give a semaphore.
94    *
95    * This routine gives @a sem, unless the semaphore is already at its maximum
96    * permitted count.
97    *
98    * @note Can be called by ISRs.
99    *
100    * @param sem Address of the semaphore.
101    *
102    * @satisfy{@req{015}}
103    */
104    __syscall void k_sem_give(struct k_sem *sem);
105
106
107
108To generate the matrix, you will first need to build the documentation,
109specifically you will need to build the doxygen XML output::
110
111   $ make doxygen
112
113Parse the generated XML data from doxygen to generate the traceability matrix.
114