Examples

This page showcases Hawkmoth in action.

The [source] links are optional, and can be enabled via the hawkmoth_source_uri option.

Overview

Source

overview.c

/**
 * The ``c:autodoc`` directive is the easiest way to extract all the
 * documentation comments from one or more source files in one go. The
 * other directives provide more fine-grained control over what to
 * document.
 *
 * This example provides a brief overview of the most common features.
 *
 * Note that the documentation comments below are **not** good examples
 * of how to document your code. Instead, the comments primarily
 * describe the features of Hawkmoth and Sphinx.
 *
 * Source files may contain documentation comments not attached to any C
 * constructs. They will be included as generic documentation comments,
 * like this one.
 */

/**
 * Macro documentation.
 */
#define ERROR -1

/**
 * Struct documentation.
 */
struct foo {
	/**
	 * Member documentation.
	 */
	const char *m1;
	/**
	 * Member documentation.
	 */
	int m2;
};

/**
 * Enum documentation.
 */
enum bar {
	/**
	 * Enumeration constant documentation.
	 */
	E1,
	/**
	 * Enumeration constant documentation.
	 */
	E2,
};

/**
 * Function documentation.
 *
 * :param p1: Parameter documentation
 * :param int p2: Parameter documentation with type
 * :return: Return value documentation
 */
int baz(int p1, int p2);

Directive

.. c:autodoc:: overview.c

Output

The c:autodoc directive is the easiest way to extract all the documentation comments from one or more source files in one go. The other directives provide more fine-grained control over what to document.

This example provides a brief overview of the most common features.

Note that the documentation comments below are not good examples of how to document your code. Instead, the comments primarily describe the features of Hawkmoth and Sphinx.

Source files may contain documentation comments not attached to any C constructs. They will be included as generic documentation comments, like this one.

ERROR

Macro documentation.

struct foo

Struct documentation.

const char *m1

Member documentation.

int m2

Member documentation.

enum bar

Enum documentation.

enumerator E1

Enumeration constant documentation.

enumerator E2

Enumeration constant documentation.

int baz(int p1, int p2)

Function documentation.

Parameters:

• p1 – Parameter documentation

• p2 (int) – Parameter documentation with type

Returns:

Return value documentation

Variable

Source

variable.c

/**
 * The name says it all.
 */
const int meaning_of_life = 42;

/**
 * The list of entries.
 *
 * Use :c:func:`frob` to frobnicate, always in :c:macro:`MODE_PRIMARY` mode.
 */
static struct list *entries;

/**
 * This is a sized array.
 */
const char array[10];

Directive

.. c:autodoc:: variable.c

Output

const int meaning_of_life

The name says it all.

static struct list *entries

The list of entries.

Use frob() to frobnicate, always in MODE_PRIMARY mode.

const char array[10]

This is a sized array.

Directive

.. c:autovar:: meaning_of_life
   :file: variable.c

Output

const int meaning_of_life

The name says it all.

Typedef

Source

typedef.c

/**
 * Typedef documentation.
 */
typedef void * list_data_t;

Directive

.. c:autotype:: list_data_t
   :file: typedef.c

Output

type list_data_t

Typedef documentation.

Macro

Source

macro.c

/**
 * Failure status.
 */
#define FAILURE 13

/**
 * Terminate immediately with failure status.
 *
 * See :c:macro:`FAILURE`.
 */
#define DIE() _exit(FAILURE)

/**
 * Get the number of elements in an array.
 *
 * :param array: An array
 * :return: Array size
 */
#define ARRAY_SIZE(array) (sizeof(array) / sizeof(array[0]))

/**
 * Variadic macros
 *
 * :param foo: regular argument
 * :param ...: variable argument
 */
#define VARIADIC_MACRO(foo, ...) (__VA_ARGS__)

Directive

.. c:autodoc:: macro.c

Output

FAILURE

Failure status.

DIE()

Terminate immediately with failure status.

See FAILURE.

ARRAY_SIZE(array)

Get the number of elements in an array.

Parameters:

• array – An array

Returns:

Array size

VARIADIC_MACRO(foo, ...)

Variadic macros

Parameters:

• foo – regular argument

• ... – variable argument

Directive

.. c:automacro:: DIE
   :file: macro.c

Output

DIE()

Terminate immediately with failure status.

See FAILURE.

Function

Source

function.c

struct list;
enum mode;

/**
 * List frobnicator.
 *
 * :param list: The list to frob.
 * :param mode: The frobnication mode.
 * :return: 0 on success, non-zero error code on error.
 * :since: v0.1
 */
int frob(struct list *list, enum mode mode);

/**
 * variadic frobnicator
 *
 * :param fmt: the format
 * :param ...: variadic
 */
int frobo(const char *fmt, ...);

Directive

.. c:autodoc:: function.c

Output

int frob(struct list *list, enum mode mode)

List frobnicator.

Parameters:

• list – The list to frob.

• mode – The frobnication mode.

Returns:

0 on success, non-zero error code on error.

Since:

v0.1

int frobo(const char *fmt, ...)

variadic frobnicator

Parameters:

• fmt – the format

• ... – variadic

Directive

.. c:autofunction:: frob
   :file: function.c

Output

int frob(struct list *list, enum mode mode)

List frobnicator.

Parameters:

• list – The list to frob.

• mode – The frobnication mode.

Returns:

0 on success, non-zero error code on error.

Since:

v0.1

Struct

Source

struct.c

/**
 * Linked list node.
 */
struct list {
	/** Next node. */
	struct list *next;

	/** Data. */
	int data;
};

Directive

.. c:autodoc:: struct.c

Output

struct list

Linked list node.

struct list *next

Next node.

int data

Data.

Directive

.. c:autostruct:: list
   :file: struct.c
   :members:

Output

struct list

Linked list node.

struct list *next

Next node.

int data

Data.

Class

Source

class.cpp

/**
 * Circle.
 */
class Circle {
private:
	/** Radius */
	int radius;

public:
	/** Constructor */
	Circle(int radius);

	/** Destructor */
	~Circle();

	/** Get the area. */
	virtual int area(void);
};

Directive

.. cpp:autoclass:: Circle
   :file: class.cpp
   :members:

Output

class Circle

Circle.

private int radius

Radius

Circle(int radius)

Constructor

~Circle(void)

Destructor

virtual int area(void)

Get the area.

Union

Source

union.c

/**
 * Onion documentation.
 */
union onion {
	/**
	 * Yellow onion.
	 */
	int yellow;
	/**
	 * Red onion.
	 */
	int red;
	/**
	 * White onion.
	 */
	int white;
};

Directive

.. c:autounion:: onion
   :file: union.c
   :members:

Output

union onion

Onion documentation.

int yellow

Yellow onion.

int red

Red onion.

int white

White onion.

Enum

Source

enum.c

/**
 * Frobnication modes for :c:func:`frob`.
 */
enum mode {
	/**
	 * The primary frobnication mode.
	 */
	MODE_PRIMARY,
	/**
	 * The secondary frobnication mode.
	 *
	 * If the enumerator is initialized in source, its value will also be
	 * included in documentation.
	 */
	MODE_SECONDARY = 2,
};

Directive

.. c:autoenum:: mode
   :file: enum.c
   :members:

Output

enum mode

Frobnication modes for frob().

enumerator MODE_PRIMARY

The primary frobnication mode.

enumerator MODE_SECONDARY = 2

The secondary frobnication mode.

If the enumerator is initialized in source, its value will also be included in documentation.

Generic Documentation Section

Source

autosection.c

/**
 * .. _Hyperlink Target:
 *
 * This is a generic documentation comment.
 *
 * Because generic documentation comments aren't attached to any symbols, the
 * comment itself has to contain a name that can be referenced from the
 * ``c:autosection`` or ``cpp:autosection`` directive.
 *
 * The name shall be from the first alphanumeric character in the comment,
 * inclusive, to the next :, ., or newline, non-inclusive. This means
 * reStructuredText hyperlink targets become reference names, like in this case,
 * but it does not have to be a hyperlink target. It could just be the first
 * sentence in the comment.
 *
 * No hyperlink targets are generated automatically. If you need to reference
 * the comment from reStructuredText, you need to add one yourself.
 */

Directive

.. c:autosection:: Hyperlink Target
   :file: autosection.c

Output

This is a generic documentation comment.

Because generic documentation comments aren’t attached to any symbols, the comment itself has to contain a name that can be referenced from the c:autosection or cpp:autosection directive.

The name shall be from the first alphanumeric character in the comment, inclusive, to the next :, ., or newline, non-inclusive. This means reStructuredText hyperlink targets become reference names, like in this case, but it does not have to be a hyperlink target. It could just be the first sentence in the comment.

No hyperlink targets are generated automatically. If you need to reference the comment from reStructuredText, you need to add one yourself.

Preprocessor

Source

preprocessor.c

/**
 * Answer to the Ultimate Question of Life, The Universe, and Everything.
 */
#ifdef DEEP_THOUGHT
#define MEANING_OF_LIFE 42
#else
#error "Does not compute."
#endif

Directive

.. c:autodoc:: preprocessor.c
   :clang: -DDEEP_THOUGHT

Output

MEANING_OF_LIFE

Answer to the Ultimate Question of Life, The Universe, and Everything.

Napoleon-style comments

Source

napoleon.c

/**
 * Custom comment transformations.
 *
 * Documentation comments can be processed using the hawkmoth-process-docstring
 * Sphinx event. You can use the built-in extensions for this, or create your
 * own.
 *
 * In this example, hawkmoth.ext.napoleon built-in extension is used to support
 * Napoleon-style documentation comments.
 *
 * Args:
 *     foo: This is foo.
 *     bar: This is bar.
 *
 * Return:
 *     Status.
 */
int napoleon(int foo, char *bar);

Directive

.. c:autodoc:: napoleon.c
   :transform: napoleon

Output

int napoleon(int foo, char *bar)

Custom comment transformations.

Documentation comments can be processed using the hawkmoth-process-docstring Sphinx event. You can use the built-in extensions for this, or create your own.

In this example, hawkmoth.ext.napoleon built-in extension is used to support Napoleon-style documentation comments.

Parameters:

• foo – This is foo.

• bar – This is bar.

Returns:

Status.

Javadoc/Doxygen-style comments

Source

javadoc.c

struct list;
enum mode;

/**
 * Custom comment transformations.
 *
 * Documentation comments can be processed using the hawkmoth-process-docstring
 * Sphinx event. You can use the built-in extensions for this, or create your
 * own.
 *
 * In this example, <tt>hawkmoth.ext.javadoc</tt> built-in extension is used to
 * support Javadoc/Doxygen-style documentation comments. You can use both \@ and
 * \\ for the commands.
 *
 * \note
 * While the most common commands and inline markup \a should work, the
 * Javadoc/Doxygen support is nowhere near complete.
 *
 * The support should be good enough for basic API documentation, including
 * things like code blocks:
 *
 * \code
 * ¯\_(ツ)_/¯
 * \endcode
 *
 * And parameter and return value descriptions, and the like:
 *
 * @param list The list to frob.
 * @param[in] mode The frobnication mode.
 * @return 0 on success, non-zero error code on error.
 * @since v0.1
 */
int frob2(struct list *list, enum mode mode);

Directive

.. c:autodoc:: javadoc.c
   :transform: javadoc

Output

int frob2(struct list *list, enum mode mode)

Custom comment transformations.

Documentation comments can be processed using the hawkmoth-process-docstring Sphinx event. You can use the built-in extensions for this, or create your own.

In this example, hawkmoth.ext.javadoc built-in extension is used to support Javadoc/Doxygen-style documentation comments. You can use both @ and \ for the commands.

Note

While the most common commands and inline markup should work, the Javadoc/Doxygen support is nowhere near complete.

The support should be good enough for basic API documentation, including things like code blocks:

¯\_(ツ)_/¯

And parameter and return value descriptions, and the like:

Parameters:

• list – The list to frob.

• mode – [in] The frobnication mode.

Returns:

0 on success, non-zero error code on error.

Since:

v0.1