Documented

src/engine/benchmark.rs

@@ -1,3 +1,7 @@
+//! # Benchmark Module
+//!
+//! Provides performance benchmarking capabilities for rendering engines.
+
 use std::{io::stdout, sync::Arc, time::Instant};
 
 use crossterm::{cursor::MoveTo, execute, terminal::Clear};
@@ -7,18 +11,26 @@ use crate::{render::Area, DrawContext, View};
 
 use super::Engine;
 
+/// Results of a benchmark run
 #[derive(Debug, Clone)]
 pub struct BenchmarkResult {
+    /// Average render time in microseconds
     pub average: u128,
+    /// Minimum render time in microseconds
     pub min: u128,
+    /// Maximum render time in microseconds
     pub max: u128,
+    /// Total time spent rendering in microseconds
     pub total_render: u128,
+    /// Total benchmark time including setup in microseconds
     pub total: u128,
 }
 
+/// Wraps an engine to benchmark its rendering performance
 pub struct Benchmark<T: Engine>(T);
 
 impl<T: Engine> Benchmark<T> {
+    /// Creates a new benchmark wrapper around the given engine
     pub fn new(engine: T) -> Self {
         Self(engine)
     }
@@ -31,6 +43,7 @@ impl<T: Engine> Engine<BenchmarkResult> for Benchmark<T> {
 
         let start = Instant::now();
 
+        // Run 40 render cycles and measure each
         for _ in 0..40 {
             let start = Instant::now();
             self.render(&cx);

src/engine/commands.rs

@@ -1,5 +1,10 @@
+//! # Commands Module
+//!
+//! Defines built-in commands for controlling the engine.
+
 use crate::engine::Command;
 
+/// Command to stop the engine and terminate the application
 pub struct Stop;
 
 impl Command for Stop {

src/engine/console.rs

@@ -1,3 +1,8 @@
+//! # Console Engine Implementation
+//!
+//! Provides a Console implementation of the Engine trait for rendering
+//! to the terminal using crossterm.
+
 use std::{
     io::{stdout, Write},
     sync::{Arc, Mutex},
@@ -14,16 +19,24 @@ use crate::{
 
 use super::Engine;
 
+/// Executes commands for the console engine
 pub struct ConsoleExecutor {
+    /// Flag indicating whether the application is running
     running: Mutex<bool>,
 }
 
+/// Console-based rendering engine
+/// 
+/// Renders components to the terminal using crossterm for cross-platform support.
 pub struct Console {
+    /// Thread functions to execute
     threads: Mutex<Vec<Arc<dyn Fn(Arc<Context>) + Send + Sync>>>,
+    /// The executor for this console
     executor: Arc<ConsoleExecutor>,
 }
 
 impl Console {
+    /// Creates a new console engine
     pub fn new() -> Self {
         Self {
             threads: Mutex::new(Vec::new()),
@@ -33,6 +46,7 @@ impl Console {
         }
     }
 
+    /// Registers a thread function to run alongside the engine
     pub fn thread<F: Fn(Arc<Context>) + Send + Sync + 'static>(&self, run: F) {
         self.threads.lock().unwrap().push(Arc::new(run));
     }
@@ -114,10 +128,12 @@ impl Engine for Console {
 }
 
 impl ConsoleExecutor {
+    /// Checks if the engine is still running
     pub fn is_running(self: &Arc<ConsoleExecutor>) -> bool {
         *self.running.lock().unwrap()
     }
 
+    /// Stops the engine
     pub fn stop(&self) -> crate::Result<()> {
         *self.running.lock()? = false;
         Ok(())

src/engine/mod.rs

@@ -1,3 +1,9 @@
+//! # Engine Module
+//!
+//! Provides the rendering engine and command execution system.
+//! The engine is responsible for initializing components, rendering frames,
+//! and handling user commands.
+
 pub mod benchmark;
 pub mod commands;
 pub mod console;
@@ -10,23 +16,40 @@ use std::{any::Any, sync::Arc};
 use crate::component::{context::Context, ComponentImpl};
 use crate::{render::Area, DrawContext, View};
 
+/// Main engine trait for rendering and running components
 pub trait Engine<Output = ()> {
+    /// Runs a component to completion
     fn run<C: ComponentImpl + 'static>(&self, component: C) -> crate::Result<Output>;
+    
+    /// Initializes a component and returns its context
     fn init<C: ComponentImpl + 'static>(&self, component: C) -> Arc<Context>;
+    
+    /// Renders the current state of a component
     fn render(&self, cx: &Arc<Context>);
+    
+    /// Sleeps between render frames (default 16ms for ~60fps)
     fn render_delay(&self) {
         crate::sleep(16);
     }
 
+    /// Renders a view within an area and returns the draw context
     fn render_view(&self, area: &Area, view: &View) -> DrawContext;
+    
+    /// Executes the drawing instructions in a draw context
     fn draw_context(&self, ctx: &DrawContext);
+    
+    /// Returns the command executor for this engine
     fn executor(&self) -> Arc<dyn CommandExecutor>;
 }
 
+/// Trait for commands that can be executed by the engine
 pub trait Command {
+    /// Returns the command as Any for downcasting
     fn as_any(&self) -> &dyn Any;
 }
 
+/// Executes commands during the application lifecycle
 pub trait CommandExecutor: Send + Sync {
+    /// Executes the given command
     fn execute_command(&self, command: &Arc<dyn Command>) -> crate::Result<()>;
 }