Generated public SDK reference

Doxygen extracts XML from Ludus's public headers; MkDocs renders the API pages with the same Material theme and search as the rest of the wiki. It is documentation tooling only: no engine link dependency or native SDK/toolchain configuration is required. config/doxygen_toolchain.json pins the official executable version, Linux x64 and macOS Apple Silicon/Intel archives from the official GitHub release and SHA-256 checksums published by Doxygen. Downloads identify the documentation client with an explicit User-Agent; the checksum is verified before extracting or executing the binary.

On macOS 15 or later, python scripts/build-api --bootstrap automatically selects Apple Silicon (arm64) or Intel (x86_64) using the Python process architecture. An Intel Python running under Rosetta selects the Intel tool. Build MkDocs first as described below; no Homebrew, disk-image mounting or system-wide installation is needed. Archives and the executable stay in ignored out/doxygen-tools/. Repeat runs verify and reuse the cached archive and restore the CLI from it, including when its installed copy is missing or damaged. Failed downloads or extraction leave an existing executable intact. Only the CLI member is extracted; the GUI and search helpers are not installed. Other hosts may use python scripts/build-api --doxygen /path/to/doxygen with the pinned version. The release binaries target macOS 15, despite the upstream download page's macOS 13+ label; older systems fail with a setup message before downloading or replacing tools. Use an explicit compatible build of the pinned Doxygen version on those systems. Plain previews never download Doxygen.

Write caller contracts

Write descriptions beside public declarations in /// or /** ... */ comments. Doxygen extracts the signature; explain the contract a caller needs.

Item	Useful description
Class or struct	Purpose, ownership, lifetime and thread-affinity rules
Function or method	Inputs/units, return/status meanings, failure effects and preconditions
Field, enum value or constant	Meaning, units, valid bounds and sentinel behavior
Alias or macro	Intended use and any evaluation/build limitations

Start multiline comments with @brief for the summary shown in member tables. Use @param, @return, @pre, @note and @warning where appropriate. Engine errors are explicit; do not add exception contracts. Preserve existing source attribution and link lengthy explanations to their architecture owner. For a concrete example, read AllocationDomain.

API comments and implementation comments

Clean code and API documentation serve different readers. Keep implementation comments for non-obvious reasoning, invariants and source attribution. Put a Doxygen contract beside the public declaration so callers can understand the API without reading its implementation. Avoid narrating obvious statements or adding descriptions that merely repeat a symbol's name.

Ordinary // comments are not extracted. Use /// before a declaration or ///< after a field or enum value. A file introduction does not document its types, and a comment before several declarations documents only the first. Give each overload its own contract; use @copydoc with an explicit qualified signature only when the contracts are identical. Keep analysis suppressions and implementation notes as ordinary comments.

For example, checked arithmetic needs a failure contract even though its name is clear:

/// Add without wrapping or saturation; false preserves out, including aliased operands.
template <Integer ValueType>
[[nodiscard]] constexpr bool TryAdd(ValueType left, ValueType right, ValueType& out) noexcept;

Separate a concise @brief from longer details with a blank documentation line. Use code formatting for header names and template expressions so angle brackets are not parsed as HTML. Check the extracted reference as well as coverage: recognizing a comment does not prove its lifetime or failure claims are correct.

Inputs and boundaries

scripts/build-api reads literal PUBLIC/INTERFACE FILE_SET public_headers lists from module CMake files. It fails on unsupported file-set expressions, missing headers or include-tree headers absent from the declared file sets. This intentionally narrow reader is not a general CMake evaluator. Changing header registration to globs, new generated inputs or complex expressions requires updating it with regressions. It never scans source/private/third-party directories as Doxygen inputs and excludes installed detail/internal helper headers.

Three generated Foundation headers are represented by their checked-in templates: build_metadata.hpp.in, assert_config.hpp.in, and profiling_config.hpp.in. They expose vocabulary, not concrete configured values. Their @...@ placeholders are explicitly identified on the reference landing page. Preprocessing is disabled to inventory native/browser declaration branches together; this is source reference, not a compiler-verified symbol set for a particular SDK profile. The renderer excludes private/protected members. detail/internal namespaces, their members and nested types are excluded by Doxygen configuration (EXCLUDE_SYMBOLS names both the namespace and its contents); coverage and rendering also skip any compound or member in such a scope, so these implementation helpers are neither counted as public API nor published. Whole-header source listings and private members are never rendered from the XML; public declaration initializers remain visible.

Build and publication

Use the documentation build commands: build MkDocs, run scripts/build-api with the pinned Doxygen, and check/package the combined documentation. Publication adds the separately validated editor payload before the full scripts/check-wiki gate. The generator writes out/api-reference/{xml,markdown,coverage.json}, then rebuilds MkDocs with those generated pages through scripts/python/wiki_api_hook.py. Only the resulting site in out/wiki/ is published. XML, generated Markdown, machine-local inputs and the baseline report are not part of the public site. Relative URLs make the combined artifact usable under GitHub Pages' /Ludus/ project path without a separate deployment.

The wiki's API overview links to the generated reference using a relative URL, so it also works in a locally served combined artifact. scripts/build-api renders XML into Markdown with escaped HTML for structured descriptions, parameter tables, return/precondition/warning callouts and linked declarations. API pages use the wiki's header, sidebar, table of contents, code highlighting and light/dark mode. The API navigation section provides namespace, type, concept and header indexes. Compound filenames and member/enum-value anchors retain their existing Doxygen URLs. The combined artifact checker requires return links on every API page and a forward link from the wiki overview; broken or removed navigation fails publication.

The existing Pages workflow performs the build, regression checks and combined link validation before uploading out/wiki/. PRs validate without publishing; main publishes the wiki and API reference together. One local search indexes guides and API symbols. Generated pages link to declaring public headers and omit edit links to fictional wiki source files. No generated HTML is committed.

Plain MkDocs builds and previews reuse the last generated Markdown when available; they do not run Doxygen or download tools. Run scripts/build-api again after header/comment changes. Without that output, MkDocs builds just the authored wiki; the combined artifact checker rejects the missing reference before publication. The renderer fails on unsupported documentation XML elements rather than silently discarding part of a contract; extend its presentation and regression tests when introducing a new structured documentation construct.

Coverage and validation

EXTRACT_ALL=YES ensures undocumented declarations remain visible. Doxygen's undocumented warning mode cannot be combined with that setting, so a separate XML gate compares missing descriptions against docs/api-undocumented.json. Keys use qualified names/kinds/signatures rather than generated Doxygen IDs. Classes/structs/unions/concepts, public members, aliases/macros/constants and enum values are covered. Namespace/file descriptions are not required.

CI rejects new gaps, changed undocumented signatures and removal of previously documented descriptions. The independent Public API documentation job runs on every pull request, without waiting for the browser editor build. It passes --baseline-ref with the PR base commit SHA and rejects any baseline additions, including replacing an old signature with a new one. The checkout must contain that commit; missing history fails rather than skipping the comparison. Existing gaps are visible in the coverage report. Resolved/deleted entries must be removed in the same change; retaining them fails the extraction gate and could otherwise allow later removal of a newly documented contract. Parameter documentation errors are handled by Doxygen warnings-as-errors; this description gate does not prove semantic completeness or automatically require every parameter. No blanket conversion of plain comments or invented contracts is performed.

out/api-reference/coverage.json reports gaps and resolved/removed entries. Remove resolved baseline entries with the change that documents them. The explicit --update-baseline switch is for a reviewed migration; do not use it to make failing coverage checks pass. It cannot be combined with --baseline-ref, and CI allows the resulting baseline only when it is a subset of the base commit's entries. Local comparison uses the same gate, for example:

out/wiki-venv/bin/python scripts/build-api --bootstrap --baseline-ref origin/main

The combined HTML checker checks API local links/assets/anchors and requires MkDocs search coverage for every wiki and API page. Tests inject missing headers, unknown generated inputs, removed descriptions, undocumented enum values, private members, detail/internal namespace members, overload/enum-value anchors, structured contracts and broken/unindexed generated pages.

Consulted references

Thanks to Dimitri van Heesch / Doxygen, Configuration and Documenting the code, for the extraction, structured comment, XML and warning contracts adopted here. Its Customizing the output: Using the XML output informs the separation between declaration extraction and site presentation. Thanks to MkDocs, Plugins and API Reference, for the hooks and generated-file interfaces used to join the normal site build. The official download page supplies the pinned archive checksums. No upstream implementation code is copied.