[LOW] Expand module-level documentation for complex systems

[MichaelFisher1997]

Problem

While the codebase has good function-level documentation (/// comments), some complex systems lack module-level documentation (//!) explaining the overall architecture, design decisions, and usage patterns.

Modules Needing Better Documentation

1. World Streaming System

• How chunks flow through states (missing -> generating -> meshing -> renderable)
• Interaction between WorldStreamer, JobSystem, and WorldRenderer
• Thread safety considerations

2. RHI Architecture

• Relationship between RHI, Vulkan backend, and RenderDevice
• How the segregated interfaces work together
• Resource lifetime management

3. LOD System

• How LOD0/LOD1/LOD2/LOD3 differ
• Relationship between LODManager and LODRenderer
• GPU data management for LOD

4. Render Graph

• How passes are ordered and executed
• Main pass lifecycle
• Pass dependencies

5. Job System

• Job prioritization strategy
• Worker thread lifecycle
• Reprioritization mechanism

Current State

Most files have minimal or no module-level documentation:

Proposed Solution

Add comprehensive module-level documentation (//!) to complex modules:

Benefits

• Faster onboarding for new developers
• Clearer understanding of system interactions
• Documentation stays in sync with code
• Better long-term maintainability

Acceptance Criteria

• Module docs for world_streamer.zig
• Module docs for rhi.zig explaining architecture
• Module docs for lod_manager.zig and lod_renderer.zig
• Module docs for render_graph.zig
• Module docs for job_system.zig
• Review and improve existing module docs

Related Files

• src/world/world_streamer.zig
• src/engine/graphics/rhi.zig
• src/world/lod_manager.zig
• src/world/lod_renderer.zig
• src/engine/graphics/render_graph.zig
• src/engine/core/job_system.zig

Estimated Effort

Low (documentation only, no code changes)

[opencode-agent]

Analysis Complete

Classification: Feature Request (documentation improvement)

Current State:

• ✅ job_system.zig - Has basic //! docs, needs expansion for prioritization/reprioritization details
• ⚠️ world_streamer.zig - Has basic //! docs, needs architecture/flow documentation
• ✅ lod_manager.zig - Well documented with //! comments
• ✅ lod_renderer.zig - Has basic //! docs
• ❌ rhi.zig - Missing module-level docs entirely
• ❌ render_graph.zig - Missing module-level docs entirely

Files Missing Documentation:

• src/engine/graphics/rhi.zig (34K LOC) - Most critical, needs comprehensive architecture docs
• src/engine/graphics/render_graph.zig (14K LOC) - Needs pass ordering/lifecycle docs

Recommendation:
The acceptance criteria looks accurate based on the codebase. Consider adding:

1. Priority ordering: Start with rhi.zig since it's the most fundamental and largest module
2. Cross-references: Link between related modules (e.g., job_system.zig → world_streamer.zig)
3. Architecture diagrams: Consider ASCII diagrams in docs for complex flows (chunk state machine, render graph)

This issue is appropriately scoped for a single PR covering all five modules since it's documentation-only with no code changes.

opencode session  |  github run