Doxygen contributor’s guide#

This guide shows Upstream Pigweed maintainers how to contribute content to Pigweed’s C/C++ API reference, which is powered by Doxygen.

For Doxygen style rules, see Doxygen style guide.

Quickstart#

Check if your module is defined in docs/doxygen/modules.h. If not, define it now.
```
/// @defgroup pw_bytes pw_bytes
/// @brief Utilities for manipulating binary data.
/// @maindocs
/// [Home](../../pw_bytes/docs.html)
/// @endmaindocs
```
@defgroup repeats the module name to ensure proper capitalization.

@brief should contain the module’s tagline as defined in docs/sphinx/module_metadata.json. If your module doesn’t have a tagline, now is a good time to create one!

The content between @maindocs and @endmaindocs should be a complete list of links to the module’s Sphinx docs.
(Optional) If your module has a large, complex API, define “submodule” groups (such as the pw_bytes_ptr subgroup shown below) in docs/doxygen/modules.h to help further organize your module’s API reference:
```
/// @defgroup pw_bytes_ptr Packed pointers
/// @ingroup pw_bytes
/// @brief Store data in unused pointer bits
```
See pw_bytes to view the rendered example. The pw_bytes group controls the module’s API reference landing page. The main page is organized by “submodules”. The pw_bytes_ptr group is one of the submodules. On that page, all APIs related to packed pointers are presented.

In your module’s main BUILD.bazel file (e.g. //pw_bytes/BUILD.bazel) create a filegroup named doxygen. For srcs, list all headers that Doxygen should process:

filegroup(
    name = "doxygen",
    srcs = [
        "public/pw_bytes/alignment.h",
        "public/pw_bytes/array.h",
        "public/pw_bytes/bit.h",
        "public/pw_bytes/byte_builder.h",
        "public/pw_bytes/endian.h",
        "public/pw_bytes/packed_ptr.h",
        "public/pw_bytes/span.h",
        "public/pw_bytes/suffix.h",
        "public/pw_bytes/units.h",
    ],
)

Important

The Doxygen build is hermetic and all inputs are explicitly defined. If you forget to include a header at this stage, Doxygen won’t know that the header exists.

In docs/doxygen/BUILD.bazel add your target to the filegroup named srcs:

filegroup(
    name = "srcs",
    srcs = [
        # …
        "//pw_bytes:doxygen",
        # …
    ]
)

In each of the headers that you’ve listed in your module’s doxygen target, add @module or @submodule annotations.

In both cases, make sure to use @} to close off your annotation. If you don’t, Doxygen may pick up internal symbols that you did not intend to publish to the C/C++ API reference.

For simple modules where you want the entire API listed on a single page, use @module:
```
namespace pw {

/// @module{pw_foo}

// …

/// @}

}  // namespace pw
```
For more complex modules with large APIs, use @submodule:
```
namespace pw {

/// @submodule{pw_bytes,ptr}

// …

/// @}

}  // namespace pw
```
@submodule{pw_bytes,ptr} will organize the API under the pw_bytes_ptr group that’s defined in docs/doxygen/modules.h.

The lack of whitespace between pw_bytes and ptr is important!

Remember to use @} to close off your annotation!
Follow the style rules in Doxygen style guide.

Link from Sphinx to Doxygen#

To link from the Sphinx docs to a Doxygen page, use the :cc: role. See Sphinx-to-Doxygen links for usage and style guidance.

Link from Doxygen to Sphinx#

Use normal Markdown links with relative paths. There is not yet any utility like :cc: for managing Doxygen-to-Sphinx links.

/// [Home](../../pw_bytes/docs.html)

Tip

Doxygen outputs all files into a single directory, so the Sphinx docs are always available two directories below (../..).