Docs Phase 3: Prototype minimal module API extractor

[MichaelFisher1997]

Parent: #609

Summary

Build a small proof-of-concept docs generator before attempting a full repo-wide MDX pipeline.

Proposed Prototype

• Add a zig build docs step only after the extractor compiles and has useful output.
• Start with representative modules such as engine-math, world-core, and engine-rhi.
• Extract module-level //! docs and /// docs for public declarations.
• Prefer public module exports over walking every implementation file indiscriminately.

Acceptance Criteria

• Prototype runs through nix develop --command zig build docs.
• Output is deterministic and reviewable.
• Include a small fixture or golden-output test so regressions are obvious.
• Document known limitations rather than trying to solve every Zig syntax case in the first pass.

[github-actions]

This is a well-scoped Feature Request for a documentation generator prototype.

Analysis:

The proposal is feasible given the codebase structure:

1. Zig's native zig doc can extract //! and /// doc comments - no custom AST parsing needed for the prototype
2. Module entry points (modules/*/src/root.zig) already re-export public APIs, matching the "prefer public module exports" requirement
3. Target modules have rich doc comments - e.g., engine-rhi/src/rhi.zig has extensive //! module docs, and world-core/src/block.zig documents the BlockType enum

Implementation approach for the prototype:

• Add a docs step to build.zig that invokes zig doc on each target module's root.zig
• Output to a docs/generated/ directory for deterministic, reviewable output
• A golden-output test can diff the generated HTML/markdown against stored fixtures

Recommendation: This is appropriately scoped as a prototype (3 modules, known limitations). Consider splitting into sub-issues if expanded:

• feat: add zig doc build step for engine-math (smallest, simplest module)
• feat: extend docs generation to world-core
• feat: add golden-output regression test

The parent issue #609 references a phased approach - this prototype aligns with Phase 1 (prototype for representative modules) and Phase 2 (establishing doc-comment standards).

opencode session  |  github run