Skip to content

MrDocs reference omits platform-specific backends #171

Description

@sgerbino

Problem

The MrDocs reference build runs on Linux, so platform detection in detail/platform.hpp only enables BOOST_COROSIO_HAS_EPOLL and BOOST_COROSIO_HAS_SELECT. Everything guarded by BOOST_COROSIO_HAS_IOCP (Windows) or BOOST_COROSIO_HAS_KQUEUE (BSD/macOS) is invisible to MrDocs.

Since MrDocs uses LLVM/Clang to parse the source, the code must actually compile — we can't simply force all platform macros to 1 because the platform-specific system headers (<sys/epoll.h>, <sys/kqueue.h>, Windows headers) won't exist.

This affects:

  • backend.hppiocp_t, kqueue_t and their tag values are omitted
  • native/native_io_context.hpp — only epoll and select specializations documented
  • native/native_tcp_socket.hpp — same
  • native/native_tcp_acceptor.hpp — same
  • native/native_signal_set.hpp — IOCP specialization omitted
  • native/native_resolver.hpp — IOCP specialization omitted
  • tcp_socket.hpp — IOCP-specific members omitted

Desired outcome

All four backends (epoll, select, kqueue, IOCP) should appear in the generated reference regardless of the build platform.

Possible approaches

  1. Documentation-only headers — Create header stubs under a BOOST_COROSIO_MRDOCS guard that unconditionally declare the public interface of each backend tag and native type without including any platform system headers. The MrDocs target already defines this macro.

  2. Multi-pass MrDocs build — Run MrDocs once per platform in CI and merge the output. Heavy infrastructure cost.

  3. Upstream MrDocs feature — Request a way to document #if-disabled regions, treating them as conditionally-available API. This would be the ideal long-term solution but depends on MrDocs supporting it.

Option 1 is the most practical near-term approach.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    Status
    Done

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions