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#

  1. 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.

  2. 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
    
  3. 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!

  4. Explicitly close the member group that the @submodule declaration created for you behind-the-scenes:

    /// @}
    
  5. To be continued…

Modifying Doxygen#

To be continued…