rustdoc for breakout in progress #77

tb_breakout/src/body2d.rs

@@ -1,21 +1,25 @@
 use super::vec2d::Vec2D;
 
+/// A body is an object that has both position and velocity; e.g., a ball in Breakout.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Body2D {
     pub position: Vec2D,
     pub velocity: Vec2D,
 }
 
 impl Body2D {
+    /// Create a new body from a position; no velocity.
     pub fn new_pos(x: f64, y: f64) -> Body2D {
         Body2D::new_detailed(x, y, 0.0, 0.0)
     }
+    /// Create a body with both a position and a velocity.
     pub fn new_detailed(x: f64, y: f64, vx: f64, vy: f64) -> Body2D {
         Body2D {
             position: Vec2D::new(x, y),
             velocity: Vec2D::new(vx, vy),
         }
     }
+    /// Update the position of this body based on a time step and its velocity.
     pub fn integrate_mut(&mut self, time_step: f64) {
         self.position += self.velocity.scale(time_step);
     }

tb_breakout/src/breakout.rs

@@ -13,9 +13,13 @@ use types::*;
 
 use rand::seq::SliceRandom;
 
-pub mod screen {
+/// This module contains constants derived from observation and measurement of the Atari 2600 game.
+mod screen {
+    /// This is the size of the screen.
     pub const GAME_SIZE: (i32, i32) = (240, 160);
+    /// This is the y-offset of the gray frame that surrounds the board.
     pub const FRAME_OFFSET: i32 = 13;
+    /// This is the thickness of the gray frame that surrounds the board.
     pub const FRAME_THICKNESS: i32 = 12;
     pub const FRAME_SUPPORT_WIDTH: i32 = 12;
 
@@ -38,18 +42,28 @@ pub mod screen {
     pub const BOARD_BOTTOM_Y: i32 = FRAME_OFFSET + FRAME_LEFT_HEIGHT;
 
     // Atari manual refers to orange, yellow, green, aqua, blue... not what images show.
+    /// This is the RGB color of the red bricks.
     pub const RED: (u8, u8, u8) = (200, 72, 72);
+    /// This is the RGB color of the dark-orange bricks.
     pub const DARK_ORANGE: (u8, u8, u8) = (198, 108, 58);
+    /// This is the RGB color of the orange bricks.
     pub const ORANGE: (u8, u8, u8) = (180, 122, 48);
+    /// This is the RGB color of the yellow bricks.
     pub const YELLOW: (u8, u8, u8) = (162, 162, 42);
+    /// This is the RGB color of the green bricks.
     pub const GREEN: (u8, u8, u8) = (72, 160, 72);
+    /// This is the RGB color of the blue bricks.
     pub const BLUE: (u8, u8, u8) = (66, 72, 200);
 
+    /// This is the point value of the rows of bricks, from top to bottom.
     pub const ROW_SCORES: &[i32] = &[7, 7, 4, 4, 1, 1];
+    /// This is the color of the rows of bricks, from top to bottom.
     pub const ROW_COLORS: &[&(u8, u8, u8)] = &[&RED, &DARK_ORANGE, &ORANGE, &YELLOW, &GREEN, &BLUE];
 
     // Atari colors have paddle, ball, and red all being the same.
+    /// The color of the paddle in the atari-py version.
     pub const PADDLE_COLOR: (u8, u8, u8) = (200, 72, 72);
+    /// The color of the ball in the atari-py version.
     pub const BALL_COLOR: (u8, u8, u8) = (200, 72, 72);
 
     pub const ROOF_SPACING: i32 = 18;

tb_breakout/src/font.rs

@@ -1,12 +1,17 @@
 use toybox_core::graphics::{load_digit_sprites, Color, Drawable, FixedSpriteData};
 
+/// The breakout font is represented with this SET character for filled in pixels.
 const SET: char = '1';
+/// The breakout font is represented with this IGNORE character for transparent pixels.
 const IGNORE: char = '.';
+/// Each digit in the breakout font has this width.
 pub const DIGIT_WIDTH: i32 = 24;
+/// Each digit in the breakout font has this height.
 #[cfg(test)]
 pub const DIGIT_HEIGHT: i32 = 12;
 
 lazy_static! {
+    /// The score display in Breakout uses this font.
     static ref DIGIT_SPRITES: Vec<FixedSpriteData> = load_digit_sprites(
         include_str!("resources/digit_sprites.txt"),
         Color::rgb(144, 144, 144),

tb_breakout/src/lib.rs

@@ -1,3 +1,5 @@
+//! The breakout crate contains the data structures and logic for a clone of the Atari 2600 game Breakout, but defined to be more flexible.
+
 extern crate serde;
 extern crate serde_json;
 extern crate toybox_core;
@@ -9,11 +11,11 @@ extern crate ordered_float;
 extern crate rand;
 
 mod body2d;
+/// This module contains the core logic of the game.
 pub mod breakout;
 mod font;
 mod types;
 mod vec2d;
 
-pub use breakout::screen;
 pub use types::Breakout;
 pub use types::State;

tb_breakout/src/types.rs

@@ -25,6 +25,8 @@ impl StartBall {
     }
 }
 
+/// This struct represents all the static data needed to create a new game of Breakout.
+/// The data in this struct represents the Toybox config for this game.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Breakout {
     /// Random number generator used to seed new games. The randomness in breakout is derived from the starting ball configurations.
@@ -104,7 +106,10 @@ pub struct StateCore {
     pub reset: bool,
 }
 
+/// The breakout game's true state has both the configuration that launched the game and information about the current frame.
 pub struct State {
+    /// This contains information about the game that does not change during gameplay, but is referenced, read-only.
     pub config: Breakout,
+    /// This contains information about the current snapshot of game state.
     pub state: StateCore,
 }

tb_breakout/src/vec2d.rs

@@ -2,7 +2,9 @@
 /// We use f64 for internal representations but we can get integer coordinates upon request for drawing.
 #[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
 pub struct Vec2D {
+    /// The x-coordinate of this vector.
     pub x: f64,
+    /// The y-coordinate of this vector.
     pub y: f64,
 }
 
@@ -20,9 +22,12 @@ impl Vec2D {
         Vec2D::new(r * theta.cos(), r * theta.sin())
     }
 
+    /// The magnitude of the vector.
     pub fn magnitude(&self) -> f64 {
         (self.x * self.x + self.y * self.y).sqrt()
     }
+
+    /// The squared magnitude of this vector; cheaper than magnitude if you just want to know which vector is biggest.
     pub fn magnitude_squared(&self) -> f64 {
         (self.x * self.x + self.y * self.y)
     }
@@ -32,16 +37,23 @@ impl Vec2D {
         self.y.atan2(self.x)
     }
 
+    /// Move a vector by another and produce a new vector.
     pub fn translate(&self, by: &Vec2D) -> Vec2D {
         Vec2D::new(self.x + by.x, self.y + by.y)
     }
+
+    /// Move a vector by another; modifying it.
     pub fn translate_mut(&mut self, by: &Vec2D) {
         self.x += by.x;
         self.y += by.y;
     }
+
+    /// Scale a vector by a constant, producing a new vector.
     pub fn scale(&self, by: f64) -> Vec2D {
         Vec2D::new(self.x * by, self.y * by)
     }
+
+    /// Scale a vector by a constant, modifying it.
     pub fn scale_mut(&mut self, by: f64) {
         self.x *= by;
         self.y *= by;
@@ -56,13 +68,19 @@ impl Vec2D {
 // For operator overloading.
 use std::ops::{Add, AddAssign};
 
+/// Support using the plus operator on vectors.
 impl Add for Vec2D {
     type Output = Vec2D;
+
+    /// This defers to translate; producing a new vector from the sum of two others.
     fn add(self, other: Vec2D) -> Vec2D {
         self.translate(&other)
     }
 }
+
+/// Support using the += operator on vectors.
 impl AddAssign for Vec2D {
+    /// This defers to translate_mut; translating a vector by another.
     fn add_assign(&mut self, other: Vec2D) {
         self.translate_mut(&other)
     }