Examples

This page showcases Hawkmoth in action.

Note

The documentation you are viewing was built without Hawkmoth and/or its dependencies (perhaps on https://readthedocs.org/). The output seen below was pre-generated statically using Hawkmoth, and should closely reflect actual results.

Macro

Source

/**
 * 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:: examples/example-10-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

Variable

Source

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

Directive

.. c:autodoc:: examples/example-20-variable.c

Output

const int meaning_of_life

The name says it all.

struct list * entries

The list of entries.

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

Typedef

Source

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

Directive

.. c:autodoc:: examples/example-30-typedef.c

Output

list_data_t

Typedef documentation.

Enum

Source

/**
 * Frobnication modes for :c:func:`frob`.
 */
enum mode {
	/**
	 * The primary frobnication mode.
	 */
	MODE_PRIMARY,
	/**
	 * The secondary frobnication mode.
	 */
	MODE_SECONDARY,
};

Directive

.. c:autodoc:: examples/example-40-enum.c

Output

enum mode

Frobnication modes for frob().

MODE_PRIMARY

The primary frobnication mode.

MODE_SECONDARY

The secondary frobnication mode.

Struct

Source

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

	/** Data. */
	list_data_t data;
};

Directive

.. c:autodoc:: examples/example-50-struct.c

Output

struct list

Linked list node.

struct list * next

Next node.

int data

Data.

Function

Source

/**
 * 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:: examples/example-70-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

Preprocessor

Source

/**
 * 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:: examples/example-70-preprocessor.c
   :clang: -DDEEP_THOUGHT

Output

MEANING_OF_LIFE

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

Compat

Source

/**
 * 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 frob2(struct list *list, enum mode mode);

Directive

.. c:autodoc:: examples/example-80-compat.c
   :compat: javadoc-liberal

Output

int frob2(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

Generic

Source

/**
 * Source files may contain documentation comments not attached to any C
 * constructs. They will be included as generic documentation comments, for
 * example to describe the design of :c:type:`list` frobnication using
 * :c:func:`frob`.
 */

Directive

.. c:autodoc:: examples/example-90-generic.c

Output

Source files may contain documentation comments not attached to any C constructs. They will be included as generic documentation comments, for example to describe the design of list frobnication using frob().