doc/contribute/doxygen/typedefs.rst

.. _typedefs:

Type Definition Documentation
#############################

The documentation of type definitions, typedefs for short, is a simple
yet tricky matter. Typedefs are aliases for other types and, as such,
need to be well documented. Always document typedefs even if the
complex type it uses is documented already.

Type Definition Comment Template
********************************

Typedefs require a simple comment explaining why they are being used and
what type they are referencing.

.. code-block:: c

   /** Brief description with the type that is being used and why. */
   typedef int t_ie;

No further explanation is needed regarding the type even if it is complex.
Each complex type must be documented whereever it was defined.
Doxygen connects the typedef and the complex type it uses automatically.

Type Definition Documentation Example
*************************************

Correct:

.. literalinclude:: irq_test_common_commented.h
   :language: c
   :lines: 69-73
   :emphasize-lines: 1, 3, 4
   :linenos:

Lines 1 and 4 name the type that is being used and with what purpose.
Even if the purpose is the same, since the types are different, two
comments are needed. Leaving line 3 blank not only increases
readability but it also helps Doxygen link the comments to the typedefs
appropriately.

Incorrect:

.. literalinclude:: ../../../../samples/include/irq_test_common.h
   :language: c
   :lines: 67-72
   :emphasize-lines: 3, 4
   :linenos:

The comments on lines 3 and 4 offer little insight into the code's behavior.
Furthermore, they do not start with
:literal:`/**` and end with :literal:`*/`. Doxygen won't add the
information to the documentation nor link it properly to the complex
type documentation.