.. _code_documentation_guidelines:

In-Code Documentation Guidelines
################################

Follow these guidelines to document your code using comments. The |project|
follows the Javadoc Doxygen comments style. We provide examples on how to
comment different parts of the code. Files, functions, defines, structures,
variables and type definitions must be documented.

We have grouped the guidelines according to the object that is being
documented. Read sections carefully since each object provides further
details as to how to document the code as a whole.

These simple rules apply to all the code that you wish to include in
the documentation:

#. Start and end a comment block with :literal:`/**` and :literal:`*/`

#. Start each line of the comment with :literal:` * `

#. Use \@ for all Doxygen special commands.

#. Files, functions, defines, structures, variables and type
   definitions must have a brief description.

#. All comments must start with a capital letter and end in a period.
   Even if the comment is a sentence fragment.

.. note::

   Always use :literal:`/**` This is a comment. :literal:`*/` if that
   comment should become part of the documentation.
   Use :literal:`/*` This comment won't appear in the documentation :
   literal:`*/` for comments that you want in the code but not in the
   documentation.

.. toctree::
   :maxdepth: 2

   doxygen_guidelines_files.rst
   doxygen_guidelines_functions.rst
   doxygen_guidelines_variables.rst
   doxygen_guidelines_defines.rst
   doxygen_guidelines_structs.rst
   doxygen_guidelines_typedefs.rst