mirror of
https://github.com/zephyrproject-rtos/zephyr
synced 2025-09-11 04:52:28 +00:00
2dd21c199e
Added a asterisk in front of every line of the comments to fully comply with the Javadoc style. Updated all cross-references to comply with the new style. Added a note indicating explicitly that enums are to be documented just as structs. Change-Id: If017e14e3e478ec28befb5c1fcae92090f91c32e Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
46 lines
1.6 KiB
ReStructuredText
46 lines
1.6 KiB
ReStructuredText
.. _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 |