59 lines
1.6 KiB
ReStructuredText
59 lines
1.6 KiB
ReStructuredText
.. _structs:
|
|
|
|
Structure Documentation
|
|
#######################
|
|
|
|
Structures, or structs for short, require very little documentation,
|
|
and it's best to document them wherever they are defined.
|
|
Structs require only a brief description detailing why they are needed.
|
|
Each variable that composes a struct needs a comment contained within
|
|
the correct syntax. A fully simplified syntax is therefore appropriate.
|
|
|
|
.. note::
|
|
|
|
Follow the same rules as struct when documenting an enum.
|
|
Use the simplified syntax to add the brief description.
|
|
|
|
Structure Comments Template
|
|
***************************
|
|
Structs 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, however, require that line 8 be left blank.
|
|
|
|
Structure Documentation Example
|
|
*******************************
|
|
|
|
Correct:
|
|
|
|
.. literalinclude:: irq_test_common_commented.h
|
|
:language: c
|
|
:lines: 102-110
|
|
: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:: irq_test_common_wrong.h
|
|
:language: c
|
|
:lines: 1-7
|
|
:emphasize-lines: 2
|
|
: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. |