You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
S23.09: Document and render the Platform adapter headers, grouped by platform #606
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.
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).
Render them — add the platform interface dirs to mkdoxy (src-dirs or
per-platform projects) so they appear in the API reference.
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.
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).
Activity