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:
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…