doc/contribute/doxygen/structs.rst

.. _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.