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>
53 lines
1.5 KiB
ReStructuredText
53 lines
1.5 KiB
ReStructuredText
.. _Structure Documentation:
|
|
|
|
Structure Documentation
|
|
#######################
|
|
|
|
Structures, or structs for short, require very little documentation.
|
|
Structs must be documented wherever they are defined. Basically,
|
|
structs only require a brief description detailing why they are needed.
|
|
Each variable that composes a struct must be commented. A fully
|
|
simplified syntax is therefore appropriate.
|
|
|
|
Structure Comments Template
|
|
***************************
|
|
Structs only have a simplified template:
|
|
|
|
.. literalinclude:: ex_struct_pre.c
|
|
:language: c
|
|
:lines: 1-11
|
|
:emphasize-lines: 8
|
|
:linenos:
|
|
|
|
Doxygen does not require any commands to recognize the different
|
|
comments. It does require that line 8 be left blank though.
|
|
|
|
Structure Documentation Example
|
|
*******************************
|
|
|
|
Correct:
|
|
|
|
.. literalinclude:: irq_test_common_commented.h
|
|
:language: c
|
|
:lines: 117-125
|
|
:emphasize-lines: 6
|
|
:linenos:
|
|
|
|
Make sure to start every comment with
|
|
:literal:`/*!` and end it with :literal:`*/`. Every comment must start
|
|
with a capital letter and end with a period.
|
|
|
|
Doxygen requires that line 6 is left blank. Ensure a blank line
|
|
separates each group of variable and comment.
|
|
|
|
Incorrect:
|
|
|
|
.. literalinclude:: ../../samples/include/irq_test_common.h
|
|
:language: c
|
|
:lines: 112-115
|
|
:emphasize-lines: 1
|
|
:linenos:
|
|
|
|
The struct has no documentation. Developers that want to expand its
|
|
functionality have no way of understanding why the struct is defined
|
|
this way nor what its components are. |