c:autodoc directive to work, the C source code must be
documented using specific documentation comment style, and the comments must
follow reStructuredText markup.
See the examples section for a quick tour of what’s possible, and read on for documentation comment formatting details.
Documentation comments are C language block comments that begin with
Because reStructuredText is sensitive about indentation, it’s strongly
recommended, even if not strictly required, to follow a uniform style for
multi-line comments. Place the opening delimiter
/** and closing delimiter
␣*/ on lines of their own, and prefix the lines in between with
Indent the actual documentation at the third column, to let Hawkmoth
consistently remove the enclosing comment markers:
/** * The quick brown fox jumps * over the lazy dog. */
One-line comments are fine too:
/** The quick brown fox jumps over the lazy dog. */
All documentation comments preceding C constructs are attached to them, and result in C Domain directives being added for them. This includes macros, functions, struct and union members, enumerations, etc.
Documentation comments followed by comments (documentation or not) are included as generic documentation.
/** * The baznicator. * * @param foo The Foo parameter. * @param bar The Bar parameter. * @return 0 on success, non-zero error code on error. * @since v0.1 */ int baz(int foo, int bar);
The compatibility support and its documentation are a work-in-progress.
Cross-Referencing C Constructs¶
The C Domain roles for cross-referencing as follows:
:c:func:`name`for functions and function-like macros.
:c:macro:`name`for simple macros and enumeration constants.
:c:type:`name`for structs, unions, enums, and typedefs.
:c:member:`name.membername`for struct and union members.