doc/contribute/doxygen/variables.rst

.. _variables:

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.
The blank line 17 is necessary to increase the clarity
of the code and also so Doxygen can determine properly where
the comment belongs.

Lines 21-23 show another acceptable way to document two variables with a
similar function. Notice that only the first variable is documented.
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 must be documented and the difference between them
must be noted.

Example 2
=========
Variables outside of functions must 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:`structs` and
:ref:`typedefs` for further details.