Docs Phase 4: Establish Zig API doc-comment standards

[MichaelFisher1997]

Parent: #609

Summary

Define documentation comment conventions so generated API docs are useful and consistent.

Areas To Cover

• //! module-level summaries.
• /// comments for public structs, enums, functions, constants, and handles.
• What public APIs need examples versus short summaries.
• How to document ownership, allocator requirements, thread-safety, GPU/resource lifetime, and coordinate-system assumptions.

Acceptance Criteria

• Add or update contributor-facing guidance for API doc comments.
• Identify high-priority modules with missing or weak public API docs.
• Keep the standard lightweight enough that it does not block normal engine development.

[github-actions]

This is a Feature Request (documentation standards). Here's my analysis:

Already exists: CONTRIBUTING.md:249 briefly mentions //! for module-level docs and /// for public API docs — but no further guidance.

Key findings:

• Well-documented modules: engine-rhi, world-worldgen, world-runtime
• High-priority modules with zero public API docs: engine-ecs (no /// on ComponentStorage, EntityId, Registry, Transform), engine-audio, engine-input (no /// on keys_down, mouse_x, etc. fields), and all root.zig re-export files
• No dedicated API doc standards document exists; all markdown docs live at repo root, not in a docs/ folder

Scope assessment: The issue is appropriately scoped — it asks for contributor guidance + identifying priority modules, not a full retroactive documentation sweep.

Suggested next steps:

1. Add an "API Documentation" section to CONTRIBUTING.md covering: //! vs /// usage, when to use examples vs summaries, and notes on ownership/allocator/thread-safety annotations
2. Prioritize engine-ecs, engine-input, and the root.zig re-export files as the first modules to get docs pass
3. Consider a docs/api-standards.md for more detailed guidance beyond the CONTRIBUTING.md scope

Not a bug, not a question — concrete feature request with clear acceptance criteria. Valid and well-scoped.

opencode session  |  github run