mirror of
https://github.com/zephyrproject-rtos/zephyr
synced 2025-08-13 20:55:57 +00:00
fb74cd4a79
The in-code Documentation Guidelines contains the best practices for documenting code using Doxygen. The guidelines offer options for both novice and expert developers to document their code in a compatible and correct manner. Fully marked and simplified templates are provided to ease the documentation effort. Examples taken directly from Tiny Mountain's code show the difference clearly. The .c files contained here are used for the examples only and do not have any function within Tiny Mountain. Finally, the doxygen.rst file was updated to include the new content. Change-Id: I6a39a54feed5fa95f2f21545c3967ff0755d85ae Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
71 lines
2.4 KiB
ReStructuredText
71 lines
2.4 KiB
ReStructuredText
.. _Variable Documentation:
|
|
|
|
Variable Documentation
|
|
######################
|
|
|
|
Variables are the smallest element that requires documentation. As such
|
|
only a brief description is required detailing the purpose of the
|
|
variable. Only significant variables have to be documented. A
|
|
significant variable is a variable that adds functionality to a
|
|
component. Review the `Variable Documentation Examples`_ to understand
|
|
what constitutes a significant variable.
|
|
|
|
Variable Comment Template
|
|
*************************
|
|
|
|
.. code-block:: c
|
|
|
|
/*! Brief description of singificant_variable's purpose. */
|
|
int significant_variable;
|
|
|
|
Variable Documentation Examples
|
|
*******************************
|
|
|
|
Example 1
|
|
=========
|
|
|
|
This example shows a function that has been fully documented following
|
|
the best practices.
|
|
|
|
.. literalinclude:: phil_fiber_commented.c
|
|
:language: c
|
|
:lines: 110-168
|
|
:emphasize-lines: 15, 18, 21-23, 25, 31
|
|
:linenos:
|
|
|
|
Lines 15 and 18 show the documentation for two variables. Notice the
|
|
blank line 17. That line is necessary not only to increase the clarity
|
|
of the code but also to avoid Doxygen not determining properly where
|
|
the comment belongs.
|
|
|
|
Lines 21-23 show another acceptable way to document two variables with a
|
|
similar function. Notice that only one of the variables is documented,
|
|
the first one. The argument can be made that **kmutex_t f2** is no
|
|
longer a significant variable because it does not add any functionality
|
|
that has not been described for **kmutex_t f1**.
|
|
|
|
Lines 25 and 31 show us a different situation. Although both variables
|
|
are of the same type and very similar, they have different purposes.
|
|
Therefore both have to be documented and the difference between them
|
|
must be noted.
|
|
|
|
Example 2
|
|
=========
|
|
Variables outside of functions have to be documented as well.
|
|
|
|
.. literalinclude:: hello_commented.c
|
|
:language: c
|
|
:lines: 133-140
|
|
:emphasize-lines: 1, 4, 7
|
|
:linenos:
|
|
|
|
As you can see the syntax of the comment does not change. Always start
|
|
the comment with :literal:`/*!` and end it with :literal:`*/`. Remember
|
|
to begin with a capital letter and end with a period, even if the
|
|
comment is only a sentence fragment.
|
|
|
|
Notice that the variable comments also apply for more complex types like
|
|
structs. The comments on lines 4 and 7 apply only to the specific
|
|
variable and not to the whole struct. Complex types must be documented
|
|
wherever they are defined. See :ref:`Structure Documentation` and
|
|
:ref:`Type Definition Documentation` for further details. |