What

Add Doxygen-compatible documentation comments to public API headers across all 8
ecosystem projects, targeting 60%+ coverage of public interfaces.

Why

All 8 projects currently have minimal inline code documentation — mostly BSD
license headers only. Public API headers lack parameter descriptions, return value
documentation, usage examples, and cross-references to guides. This forces users
to read implementation code or external docs to understand API contracts.

Where

How

Documentation Comment Standard

/// @brief Creates a thread pool with the specified number of workers.
///
/// The pool uses work-stealing scheduling by default. Workers are started
/// immediately upon construction.
///
/// @param worker_count Number of worker threads. Pass 0 to use
///        std::hardware_concurrency().
/// @param queue_type Queue selection strategy for task distribution.
/// @return Result containing the thread pool, or an error if creation failed.
///
/// @code
/// auto pool = create_pool(4, queue_type::lock_free);
/// if (pool.has_value()) {
///     pool->submit([] { /* work */ });
/// }
/// @endcode
///
/// @see docs/QUEUE_SELECTION_GUIDE.md for queue type recommendations
/// @see docs/ARCHITECTURE.md §2 for thread pool design rationale
[[nodiscard]] auto create_pool(
    std::size_t worker_count = 0,
    queue_type type = queue_type::lock_free
) -> result<thread_pool>;

Documentation Rules

1. All public functions/methods: @brief, @param, @return
2. Complex functions: Add @code example block
3. Design-sensitive APIs: Add @see reference to ADR or architecture doc
4. Template parameters: Use @tparam
5. Deprecated APIs: Use @deprecated with migration guidance
6. Thread safety: Document with @note Thread-safe or @warning Not thread-safe

Priority Order (per project)

1. P0: Core facade/entry-point headers (the first thing users include)
2. P1: Data type headers (Result, Value, Metric, etc.)
3. P2: Configuration/builder headers
4. P3: Internal utility headers (lower priority)

Implementation Steps

1. Identify public headers per project (exported in CMake install targets)
2. Start with P0 headers — core entry points
3. Add @brief + @param + @return to all public functions
4. Add @code examples to frequently-used APIs
5. Add @see cross-references to docs/ files
6. Verify Doxygen generation produces clean output (no warnings)

Acceptance Criteria

• 60%+ of public API functions have @brief documentation
• All public functions have @param and @return tags
• Core entry-point headers (P0) have 100% coverage
• At least 1 @code example per header file
• @see references link to relevant docs/ files
• Doxygen generates without warnings on documented headers
• Existing Doxygen CI workflows (from docs(doxygen): Standardize Doxygen configuration and GitHub Pages deployment across ecosystem #461) pass

Related

• Part of docs: Ecosystem documentation improvement — enterprise-level standardization #559 (Ecosystem documentation improvement)
• Builds on docs(doxygen): Standardize Doxygen configuration and GitHub Pages deployment across ecosystem #461 (Doxygen configuration — already completed)