Working with upstream Pigweed’s Doxygen system#

The official Pigweed C/C++ API reference is powered by Doxygen. This guide shows Upstream Pigweed maintainers how to:

Author content for the Pigweed C/C++ API reference
Modify the upstream Pigweed Doxygen system itself

Note

This document is a work in progress.

Authoring content#

Check if your module is defined in //docs/doxygen/modules.h. If not, define it now.

/// @defgroup pw_async2 pw_async2
/// @brief Cooperative async tasks for embedded.
/// @details Main docs: [Home](../../pw_async2/docs.html) |
/// [Quickstart](../../pw_async2/quickstart.html) |
/// [Codelab](../../pw_async2/codelab.html) |
/// [Guides](../../pw_async2/guides.html) |
/// [Code size analysis](../../pw_async2/code_size.html) |
/// [Coroutines](../../pw_async2/coroutines.html) |
/// [Backends](../../pw_async2/backends.html)

@defgroup repeats the module name to ensure proper capitalization.

@brief should contain the module’s tagline as defined in //docs/sphinx/module_metadata.json.

@details should be a complete list to the module’s main docs.

Create @submodule groups to help further categorize your module’s API:

/// @defgroup pw_async2_adapters Pendable adapters
/// @ingroup pw_async2
/// @brief Pendable wrappers and helpers

Add a @submodule declaration within each header file that you want Doxygen to process.
```
namespace pw {

/// @submodule{pw_async2,adapters}

…
```
The @submodule declaration must be nested within the pw namespace. It can’t be outside of the pw namespace.

The lack of whitespace between pw_async2 and adapters is important!
Explicitly close the member group that the @submodule declaration created for you behind-the-scenes:
```
/// @}
```
To be continued…

Modifying Doxygen#

To be continued…