Skip to content

S23.09: Document and render the Platform adapter headers, grouped by platform #606

Closed

Description

@DavidCozens

Parent epic: #246

Goal

Extend the API reference beyond Core/Interface to the platform adapter headers
under Platform/*/Interface, documented to the same value-add-only contract bar
as S23.02 (#248), and presented so each platform reads as a distinct set.

Surfaced while reviewing the S23.02 mkdoxy output (PR #604): mkdoxy scans only
Core/Interface, so the platform interface headers do not render at all, and
the generated reference is framed in C++ terms.

Scope

78 headers across 10 platforms: Posix (19), Windows (19), LwipRaw (11),
PlusTcp (8), MbedTls (6), OpenSsl (6), FreeRtos (3), Atomics (2), FatFs (2),
PlusFat (2).

  1. Doc-comment pass over every Platform/*/Interface/*.h to the S23.02 bar
    — contract only (ownership / lifetime / blocking / error-and-return
    semantics / pool + Null-fallback behaviour), self-evident symbols left bare,
    never restating the signature, verified against the implementation. See the
    value-add bar in the project memory (feedback_comments_add_value).
  2. Render them — add the platform interface dirs to mkdoxy (src-dirs or
    per-platform projects) so they appear in the API reference.
  3. Platforms visible as a set — each platform (Posix / Windows / LwipRaw /
    PlusTcp / MbedTls / OpenSsl / FreeRtos / Atomics / FatFs / PlusFat) should
    read as a distinct group. Open design point: the directory split may be
    enough, or we add per-platform nav sections / separate mkdoxy projects /
    Doxygen module grouping. Decide during implementation.
  4. C-idiomatic reference (folded in here, not a separate story/PR) — drop
    the C++-oriented generated navigation (Namespaces / Classes / Class
    Hierarchy / class-members) so a C library reads as headers -> functions ->
    structs. OPTIMIZE_OUTPUT_FOR_C is already enabled; this is about the
    generated nav/overview pages, not the flag.

Done when

  • Every Platform/*/Interface header has contract doc-comments (or is
    explicitly @internal).
  • The platform headers render in the site, visibly grouped per platform.
  • No C++-only navigation sections remain in the API reference.
  • mkdocs build --strict is green (the docs-build CI job).

Not in scope

  • Interface -> implementer -> consumer relationship visualisation (the third
    render concern; still under design, tracked separately when the approach is
    settled).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    storyStory issue

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions