[R2-13][P4] Raise public API doc coverage from 14.6% → ≥40%

[MichaelFisher1997]

Part of #839 — [Audit][Round 2] A++ umbrella.
Phase: P4 · Finding: R2-13

Problem

Public API /// doc coverage is 14.6% (331 of 2,273 non-test pub fn). AGENTS.md mandates: "Use //! for module-level docs, /// for public API documentation". The RHI, world-runtime, and game-ui public surfaces — the boundaries other modules consume — are especially underspecified.

This issue is a sibling of #609–#615 (generated API docs pipeline) — those cover generation; this covers content.

Evidence

Round 2 readability audit:

• Top-level //! module docs: strong — present in major files (lod_manager.zig, log.zig, world.zig)
• pub const types: mixed — many documented, many not
• Hot-path pub fn: undocumented — e.g. chooseVertexCapacityMb, processGpuMeshing, applyBlockMutation, renderShadowPass
• Worst-documented clusters: game-ui screens, engine-rhi interface methods
• Best-documented clusters: lod_* modules

Coverage by area (approximate)

Area	/// coverage	Priority
engine-rhi/src/rhi.zig (19 interfaces + 5 wrappers)	~25%	High (the central contract)
world-runtime/src/world.zig (33-method vtable)	~15%	High (consumed by game layer)
game-ui/src/screens/*.zig	~5%	Medium
engine-math, world-core, world-meshing	~40%	Low (already decent)

Fix

Tier the work by leverage:

Tier 1 — Document the RHI contract (engine-rhi)

Document every method on every I*Context interface (rhi.zig:107-1089) and every wrapper method. Each /// should answer:

• Purpose: what does this do?
• Preconditions: what state must the caller guarantee?
• Postconditions: what does the backend guarantee?
• Errors: which RhiError variants and what they mean
• Threading: main-thread-only? safe from workers?

Pattern:

/// Stages a buffer upload for the next frame's command buffer.
///
/// `offset` is relative to the start of `handle`'s device memory.
/// The upload is queued; it completes no later than the next call to `endFrame`.
///
/// **Errors:**
/// - `RhiError.OutOfMemory` if the staging arena is full
/// - `RhiError.InvalidHandle` if `handle` is 0 or stale
///
/// **Threading:** main thread only.
pub fn uploadBuffer(self: IResourceFactory, handle: BufferHandle, offset: u64, data: []const u8) RhiError!void

Target: 100% /// coverage on engine-rhi. ~150 functions. Lifts overall coverage by ~6%.

Tier 2 — Document the IWorld facade (world-runtime)

Document every method on the 33-method vtable (world.zig) and the 3 role interfaces (IWorldSimulation/Render/Telemetry). Same pattern as Tier 1.

Target: 100% /// coverage on world-runtime public surface. ~165 functions. Lifts overall coverage by ~7%.

Tier 3 — Document game-ui screen lifecycles

Document the public entry points of each screen (init, deinit, update, draw, onInput, onNavigate). Focus on lifecycle invariants — when can each be called?

Target: 80% /// coverage on game-ui. ~85 functions.

Tier 4 — Sweep remaining modules

Add /// to any undocumented pub fn in engine-math (gap), world-core, world-meshing, engine-graphics, etc. Use grep -rE '^pub fn' modules/ | grep -B1 -v '^[^-]*///' to find undocumented ones.

Target end state

• Overall /// coverage: ≥ 40% (currently 14.6%)
• Tier 1 + Tier 2 modules: ≥ 90% (the contracts)
• All pub const types: ≥ 60%

Verification

• Manual: spot-check 10 random pub fn per tier — confirm /// is present and useful
• Add a CI lint check (out of scope here; tracked in Production-Readiness Audit: missing CI / lint / benchmark / regression guardrails #834) that fails on undocumented pub fn in Tier 1/2 modules
• grep -rE '^pub fn' modules/engine-rhi/ | wc -l vs grep -rE '^///' modules/engine-rhi/ | wc -l — Tier 1 ratio should approach 1:1

Constraints

• Documentation-only PRs — no code changes.
• One PR per tier (or per module within a tier for reviewability).
• Conventional commit: docs(engine-rhi): document I*Context vtables, docs(world-runtime): document IWorld facade, etc.
• Do not add /// to test blocks or fn (non-pub) — out of scope.
• Each doc comment should answer a real question a consumer would ask. Avoid stub docs like /// Initializes — be specific.

Notes

• Coordinate with Docs Phase 1: Decide generated API docs strategy #610–Docs Phase 4: Establish Zig API doc-comment standards #613 (generated API docs pipeline) — Tier 1 + Tier 2 docs are the input those phases will consume.
• AGENTS.md update: consider adding an explicit "minimum doc coverage for new pub fn" rule. Out of scope here.
• Stretch goal: a coverage bot that comments on PRs introducing undocumented pub fn in Tier 1/2 modules. Out of scope here; tracked in Production-Readiness Audit: missing CI / lint / benchmark / regression guardrails #834.

Tracking: #839

[github-actions]

Analysis — R2-13 (Public API Doc Coverage)

Classification: Feature Request (documentation effort). Well-scoped with a clear tiered strategy; the proposed doc-comment pattern (Purpose / Preconditions / Postconditions / Errors / Threading) is sound and aligns with Zig community conventions.

Validation against the codebase

Measured counts disagree with the estimates in the issue body:

Area	Issue estimate	Actual (grep)
engine-rhi pub fn	~150	262
world-runtime pub fn	~165	164 ✓
game-ui pub fn	~85	108
game-ui /// coverage	~5%	1.9% (2/108)
rhi.zig I* interfaces	19 + 5 wrappers	21 I consts*; wrappers.zig is 9 lines (likely re-exports)
rhi.zig interface line range	107–1089	Interfaces actually live at 362–1170
world.zig vtable size	33 methods	106 pub fn total across IWorld + IWorldSimulation + IWorldRenderView + IWorldTelemetry

Net: the true scope is larger than the issue estimates — engine-rhi alone is 262 functions vs ~150.

Issues with the proposed verification grep

grep -rE '^pub fn' modules/ | grep -B1 -v '^[^-]*///'

This won't behave as intended: grep -r prefixes each line with path:, so the inner pattern ^[^-]*/// never matches. A single-pass awk over files is needed:

awk 'FNR==1{fn=0} /^\s*pub fn/{fn=1; line=FILENAME":"FNR":"$0; next} /^\s*\/\/\//{if(fn){fn=0}; next} {if(fn){print line; fn=0}}' modules/engine-rhi/src/*.zig

Worth fixing before CI gating (#834) — the audit itself can't run on the broken command.

Scope concerns

1. Tier 1 is too large for one PR. ~262 functions in a single module is hard to review and hard to revert. Recommend splitting Tier 1 by interface cluster, one PR each:
   • resource factory / pipeline / shaders
   • shadow / water / UI contexts
   • render-state / SSAO / debug overlay
   • compute / render / pass orchestration
   • post-process / effects / native handles
   • screenshot
2. Tier 4 risks becoming a kitchen-sink PR. Recommend deferring until the pattern is battle-tested on Tiers 1–3, and per-module rather than sweep.
3. game-ui is worse than stated. 1.9% coverage, not 5%. Each screen file (except world_list.zig) currently has zero /// lines. Tier 3 may warrant its own per-screen PRs.
4. Baseline measurement is missing. The 14.6% figure is loose. Recommend a one-off pre-flight PR that adds a measurement script + CI check (and which the broken-grep fix above would enable), before any docs work begins — this prevents regressions and gives every later PR a clear before/after delta.

Coordination

• Docs Phase 1: Decide generated API docs strategy #610–Docs Phase 4: Establish Zig API doc-comment standards #613 (generated API docs pipeline): Tier 1 + Tier 2 are the input those phases will consume. Getting the rhi.zig pattern right is the highest-leverage first step.
• Production-Readiness Audit: missing CI / lint / benchmark / regression guardrails #834 (CI lint check): coordinate the measurement script so both this issue and Production-Readiness Audit: missing CI / lint / benchmark / regression guardrails #834 consume the same source of truth.
• AGENTS.md update (out of scope here): a "minimum /// coverage for new pub fn in Tier 1/2 modules" rule is a worthwhile follow-up, but only after the pattern is established.

Suggested first PR

A small, low-risk starter that proves the pattern and the tooling:

1. Fix the verification grep / add an awk-based script.
2. Document the 5 highest-traffic functions in rhi.zig — candidates: uploadBuffer, createBuffer, createTexture, beginFrame, endFrame — using the full Purpose/Preconditions/Postconditions/Errors/Threading pattern from the issue.
3. Capture before/after /// coverage from the script.
4. Land the doc-comment pattern in AGENTS.md (minimal one-liner) so subsequent PRs follow it.

This gets a 1% lift on engine-rhi, validates the pattern, and unblocks both #610–#613 and #834 without committing to the full ~400-function sweep in any single PR.

Tracking: #839

[github-actions]

Comment posted to #852.

Summary of analysis:

• Classification: Feature Request (documentation). Tiered strategy is sound; the Purpose/Preconditions/Postconditions/Errors/Threading pattern is excellent.
• Scope is larger than estimated:
  • engine-rhi: 262 pub fn (issue said ~150)
  • game-ui: 108 pub fn at 1.9% coverage (issue said ~5%)
  • rhi.zig has 21 I* consts spanning lines 362–1170, not 19 + 5 wrappers at 107–1089
  • world.zig has 106 pub fn across 4 interfaces, not 33
• Verification grep is broken (grep -r prefixes lines with path:, breaking the inner regex). Proposed a working awk one-liner.
• Recommend splitting Tier 1 by interface cluster (6 PRs) instead of one mega-PR; defer Tier 4 sweep; add a pre-flight baseline-measurement PR before any docs work.
• Suggested first PR: fix the grep, document 5 highest-traffic rhi.zig functions to validate the pattern, then scale out.

opencode session  |  github run