In-Code Documentation

Doxygen extracts the in-code documentation automatically from the code. Doxygen generates XML files that the 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.

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:

  1. Start and end a comment block with /** and */
  2. Start each line of the comment with *
  3. Use @ for all Doxygen special commands.
  4. Files, functions, defines, structures, variables and type definitions must have a brief description.
  5. 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. /** 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. /* This style of comment won't appear in the docs */