doc

lib/src/handler.rs

@@ -1,6 +1,34 @@
+//! # AppHandler Trait — User-Defined Game Logic Interface
+//!
+//! Defines the `AppHandler` trait that users implement to inject their game logic into the render loop.
+//! Provides two callback points: `update()` for pre-render logic (physics, input processing) and
+//! `render()` for draw call execution. Both methods receive mutable access to the `App` facade so
+//! users can modify resources, entities, or other state during each frame iteration.
+//!
+//! ## Interaction with Other Modules
+//! - **app**: The orchestrator calls update() before rendering and render() during the RedrawRequested event.
+//!   AppHandler has no direct knowledge of wgpu internals — it operates only through the App facade.
+//! - **scene::Scene**: Users typically manipulate app.scene inside these callbacks to add/remove entities.
+//! - **pipeline::PipelineCache**: Users may create new Materials via cache.get_or_create() in update().
+//!
+//! ## Architecture Note
+//! Per ARCHI_APP.md, this trait is one half of the "App" facade pattern. It enables a declarative workflow
+//! where users define their game logic without touching WGPU directly, while keeping the freedom to build
+//! the engine "brick by brick" through direct Context/PipelineCache/Renderer manipulation if needed.
+
 use crate::app::App;
 
+/// Trait defining user-provided game logic injected into the render loop at two callback points.
+/// Users implement this trait to define what happens per-frame: update (pre-render logic) and
+/// render (draw call execution). Default implementations provide empty update for convenience.
 pub trait AppHandler {
+    /// Called once per frame before rendering begins. Used for physics updates, input processing,
+    /// entity management, and any other pre-render logic. Default implementation does nothing.
+    /// Inputs: _app — mutable reference to the App facade providing access to all subsystems.
     fn update(&mut self, _app: &mut App) {}
+    /// Called during each RedrawRequested event after frame acquisition. Used for executing draw calls
+    /// by iterating Scene entities and calling app.renderer.render(view, mesh, material) per entity.
+    /// Must be implemented — called every frame that needs rendering.
+    /// Inputs: app — mutable reference to the App facade providing access to all subsystems.
     fn render(&mut self, app: &mut App);
 }