docs: minor documentation commentsa cross project

src/animation.rs

@@ -1,3 +1,4 @@
+//! This module provides a simple animation system for textures.
 use sdl2::{
     rect::Rect,
     render::{Canvas, Texture},
@@ -6,18 +7,37 @@ use sdl2::{
 
 use crate::direction::Direction;
 
+/// An animated texture, which is a texture that is rendered as a series of
+/// frames.
 pub struct AnimatedTexture<'a> {
     raw_texture: Texture<'a>,
+    /// The current tick of the animation.
     ticker: u32,
+    /// Whether the animation is currently playing in reverse.
     reversed: bool,
+    /// The offset of the texture, in pixels.
     offset: (i32, i32),
+    /// The number of ticks per frame.
     ticks_per_frame: u32,
+    /// The number of frames in the animation.
     frame_count: u32,
+    /// The width of each frame, in pixels.
     frame_width: u32,
+    /// The height of each frame, in pixels.
     frame_height: u32,
 }
 
 impl<'a> AnimatedTexture<'a> {
+    /// Creates a new `AnimatedTexture`.
+    ///
+    /// # Arguments
+    ///
+    /// * `texture` - The texture to animate.
+    /// * `ticks_per_frame` - The number of ticks to display each frame for.
+    /// * `frame_count` - The number of frames in the animation.
+    /// * `frame_width` - The width of each frame.
+    /// * `frame_height` - The height of each frame.
+    /// * `offset` - The offset of the texture, in pixels.
     pub fn new(
         texture: Texture<'a>,
         ticks_per_frame: u32,
@@ -38,12 +58,14 @@ impl<'a> AnimatedTexture<'a> {
         }
     }
 
-    // Get the current frame number
+    /// Returns the current frame number.
     fn current_frame(&self) -> u32 {
         self.ticker / self.ticks_per_frame
     }
 
-    // Move to the next frame. If we are at the end of the animation, reverse the direction
+    /// Advances the animation by one tick.
+    ///
+    /// The animation will play forwards, then backwards, then forwards, and so on.
     pub fn tick(&mut self) {
         if self.reversed {
             self.ticker -= 1;
@@ -60,7 +82,7 @@ impl<'a> AnimatedTexture<'a> {
         }
     }
 
-    // Calculate the frame rect (portion of the texture to render) for the given frame.
+    /// Calculates the source rectangle for the given frame.
     fn get_frame_rect(&self, frame: u32) -> Rect {
         if frame >= self.frame_count {
             panic!("Frame {} is out of bounds for this texture", frame);
@@ -74,6 +96,13 @@ impl<'a> AnimatedTexture<'a> {
         )
     }
 
+    /// Renders the animation to the canvas.
+    ///
+    /// # Arguments
+    ///
+    /// * `canvas` - The canvas to render to.
+    /// * `position` - The position to render the animation at.
+    /// * `direction` - The direction the animation is facing.
     pub fn render(
         &mut self,
         canvas: &mut Canvas<Window>,
@@ -84,7 +113,15 @@ impl<'a> AnimatedTexture<'a> {
         self.tick();
     }
 
-    // Functions like render, but only ticks the animation until the given frame is reached.
+    /// Renders the animation to the canvas, but only ticks the animation until
+    /// the given frame is reached.
+    ///
+    /// # Arguments
+    ///
+    /// * `canvas` - The canvas to render to.
+    /// * `position` - The position to render the animation at.
+    /// * `direction` - The direction the animation is facing.
+    /// * `frame` - The frame to render until.
     pub fn render_until(
         &mut self,
         canvas: &mut Canvas<Window>,
@@ -92,7 +129,9 @@ impl<'a> AnimatedTexture<'a> {
         direction: Direction,
         frame: u32,
     ) {
-        // TODO: If the frame we're targeting is in the opposite direction (due to self.reverse), we should pre-emptively reverse.
+        // TODO: If the frame we're targeting is in the opposite direction (due
+        // to self.reverse), we should pre-emptively reverse. This would require
+        // a more complex ticking mechanism.
         let current = self.current_frame();
         self.render_static(canvas, position, direction, Some(current));
 
@@ -101,7 +140,14 @@ impl<'a> AnimatedTexture<'a> {
         }
     }
 
-    // Renders a specific frame of the animation. Defaults to the current frame.
+    /// Renders a specific frame of the animation.
+    ///
+    /// # Arguments
+    ///
+    /// * `canvas` - The canvas to render to.
+    /// * `position` - The position to render the animation at.
+    /// * `direction` - The direction the animation is facing.
+    /// * `frame` - The frame to render. If `None`, the current frame is used.
     pub fn render_static(
         &mut self,
         canvas: &mut Canvas<Window>,