docs: document many major functions, types, enums for important functionality

src/texture/animated.rs

@@ -1,11 +1,19 @@
 use crate::error::{AnimatedTextureError, GameError, GameResult, TextureError};
 use crate::texture::sprite::AtlasTile;
 
+/// Frame-based animation system for cycling through multiple sprite tiles.
+///
+/// Manages automatic frame progression based on elapsed time.
+/// Uses a time banking system to ensure consistent animation speed regardless of frame rate variations.
 #[derive(Debug, Clone)]
 pub struct AnimatedTexture {
+    /// Sequence of sprite tiles that make up the animation frames
     tiles: Vec<AtlasTile>,
+    /// Duration each frame should be displayed (in seconds)
     frame_duration: f32,
+    /// Index of the currently active frame in the tiles vector
     current_frame: usize,
+    /// Accumulated time since the last frame change (for smooth timing)
     time_bank: f32,
 }
 
@@ -25,6 +33,16 @@ impl AnimatedTexture {
         })
     }
 
+    /// Advances the animation by the specified time delta with automatic frame cycling.
+    ///
+    /// Accumulates time in the time bank and progresses through frames when enough
+    /// time has elapsed. Supports frame rates independent of game frame rate by
+    /// potentially advancing multiple frames in a single call if `dt` is large.
+    /// Animation loops automatically when reaching the final frame.
+    ///
+    /// # Arguments
+    ///
+    /// * `dt` - Time elapsed since the last tick (typically frame delta time)
     pub fn tick(&mut self, dt: f32) {
         self.time_bank += dt;
         while self.time_bank >= self.frame_duration {

src/texture/sprite.rs

@@ -8,8 +8,10 @@ use std::collections::HashMap;
 
 use crate::error::TextureError;
 
+/// Atlas frame mapping data loaded from JSON metadata files.
 #[derive(Clone, Debug, Deserialize)]
 pub struct AtlasMapper {
+    /// Mapping from sprite name to frame bounds within the atlas texture
     pub frames: HashMap<String, MapperFrame>,
 }
 
@@ -72,10 +74,19 @@ impl AtlasTile {
     }
 }
 
+/// High-performance sprite atlas providing fast texture region lookups and rendering.
+///
+/// Combines a single large texture with metadata mapping to enable efficient
+/// sprite rendering without texture switching. Caches color modulation state
+/// to minimize redundant SDL2 calls and supports both named sprite lookups
+/// and optional default color modulation configuration.
 pub struct SpriteAtlas {
+    /// The combined texture containing all sprite frames
     texture: Texture<'static>,
+    /// Mapping from sprite names to their pixel coordinates within the texture
     tiles: HashMap<String, MapperFrame>,
     default_color: Option<Color>,
+    /// Cached color modulation state to avoid redundant SDL2 calls
     last_modulation: Option<Color>,
 }
 
@@ -89,6 +100,12 @@ impl SpriteAtlas {
         }
     }
 
+    /// Retrieves a sprite tile by name from the atlas with fast HashMap lookup.
+    ///
+    /// Returns an `AtlasTile` containing the texture coordinates and dimensions
+    /// for the named sprite, or `None` if the sprite name is not found in the
+    /// atlas. The returned tile can be used for immediate rendering or stored
+    /// for repeated use in animations and entity sprites.
     pub fn get_tile(&self, name: &str) -> Option<AtlasTile> {
         self.tiles.get(name).map(|frame| AtlasTile {
             pos: U16Vec2::new(frame.x, frame.y),