Syntax

For the Hawkmoth autodoc directives to work, the C or C++ source code must be documented using specific documentation comment style, and the comments must follow reStructuredText markup.

Optionally, the syntax may be extended to support e.g. Javadoc/Doxygen and Napoleon style comments.

See the examples section for a quick tour of what’s possible, and read on for documentation comment formatting details.

Documentation Comments

Documentation comments are C/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 or C++ constructs are attached to them, and result in C or C++ Domain directives being added for them accordingly. This includes macros, functions, struct and union members, enumerations, etc.

Documentation comments followed by comments (documentation or not) are included as normal paragraphs in the order they appear.

Info Field Lists

Use reStructuredText field lists for documenting function parameters, return values, and arbitrary other data. Sphinx recognizes some info fields, such as param and return, and formats them nicely.

/**
 * 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);

Extending the Syntax

Hawkmoth supports extending the syntax using built-in and custom extensions that convert the comments to reStructuredText.

The hawkmoth.ext.javadoc extension provides limited support for Javadoc and Doxygen style comments, and the hawkmoth.ext.napoleon extension provides support for sphinx.ext.napoleon style comments.

Cross-Referencing C and C++ Constructs

Under the hood, the Hawkmoth directives generate corresponding C and C++ domain directives. For example, c:autovar produces c:var. Use the Sphinx C Domain Roles and C++ Domain Roles for cross-referencing accordingly.

For example:

• :c:var:`name` for variables.

• :c:func:`name` for functions and function-like macros.

• :cpp:class:`name` for classes.

• :c:member:`name.membername` for struct and union members.

The C++ Domain does not have a cpp:macro directive, however, so all macros generate documentation using the C Domain c:macro directive. This also means macros have to be referenced using the c:macro role, even when otherwise using C++ Domain directives.

See the Sphinx Basic Markup and generic Cross-referencing syntax for further details on cross-referencing, and how to specify the default domain for brevity.