fb74cd4a79
The in-code Documentation Guidelines contains the best practices for documenting code using Doxygen. The guidelines offer options for both novice and expert developers to document their code in a compatible and correct manner. Fully marked and simplified templates are provided to ease the documentation effort. Examples taken directly from Tiny Mountain's code show the difference clearly. The .c files contained here are used for the examples only and do not have any function within Tiny Mountain. Finally, the doxygen.rst file was updated to include the new content. Change-Id: I6a39a54feed5fa95f2f21545c3967ff0755d85ae Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
44 lines
1.5 KiB
ReStructuredText
44 lines
1.5 KiB
ReStructuredText
.. _In-Code Documentation Guidelines:
|
|
|
|
In-Code Documentation Guidelines
|
|
################################
|
|
|
|
Follow these guidelines to document your code using comments. 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 the information regarding all elements carefully since
|
|
each type of 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:`*/`
|
|
|
|
#. 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.
|
|
|
|
.. important::
|
|
|
|
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 |