e973119ef0
To make the documentation readable from the source I want to get rid of the substitutions for the project name an code name. This does not add any values and makes it unreadable when looking at the text files directly. It also causes some issues when people use those without actually knowing what they represent, resulting in some weird and redundant language. Change-Id: Icc70eef90966ed19531c3406fe7a6d1866f7d81d Signed-off-by: Anas Nashif <anas.nashif@intel.com>
61 lines
No EOL
2 KiB
ReStructuredText
61 lines
No EOL
2 KiB
ReStructuredText
.. _in-code:
|
|
|
|
In-Code Documentation
|
|
#####################
|
|
|
|
Doxygen extracts the in-code documentation automatically from the code. Doxygen
|
|
generates XML files that the :program:`Breathe` extension imports into Sphinx.
|
|
|
|
The Doxygen pass is independent from the Sphinx pass. Using Breathe to link
|
|
them together, we can reference the code in the documentation and vice-versa.
|
|
|
|
.. _doxygen_guides:
|
|
|
|
In-Code Documentation Guides
|
|
****************************
|
|
|
|
Follow these guides to document your code using comments. The Zephyr Project
|
|
follows the Javadoc / Doxygen commenting 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 guides according to the object that is being
|
|
documented. Read sections carefully, as 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 be in sentence-form: begin with a capital letter and
|
|
end in a period, even when the comment is a sentence fragment.
|
|
|
|
.. note::
|
|
Always use this syntax when your intention is to have that comment
|
|
become part of the documentation.
|
|
:literal:`/** This comment style will show up in docs. */`
|
|
Alternatively, use the single-asterisk syntax when your intention
|
|
is for that comment to appear in the code, but not in the documentation.
|
|
:literal:`/* This style of comment won't appear in the docs */`
|
|
|
|
.. _Javadoc / Doxygen:
|
|
http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
files
|
|
functions
|
|
variables
|
|
defines
|
|
structs
|
|
typedefs
|
|
groups |