From 35b555a04bb2d8a21b5324f07abd30f37c86f1e3 Mon Sep 17 00:00:00 2001 From: Nicolas <> Date: Fri, 15 Apr 2022 07:42:01 +0200 Subject: [PATCH] Add more comments --- src/animation/circle.rs | 1 + src/animation/mod.rs | 10 ++++++++++ src/animation/rhombus.rs | 1 + src/choose.rs | 5 +++++ src/color.rs | 1 + src/fill/circle.rs | 1 + src/fill/level.rs | 1 + src/fill/mod.rs | 2 ++ src/fill/stripes.rs | 1 + src/main.rs | 7 +++++++ src/render.rs | 5 +++++ src/runner.rs | 1 + src/sampler.rs | 6 ++++++ src/surface.rs | 9 ++++++++- src/timer.rs | 4 ++++ src/vec.rs | 6 ++++++ 16 files changed, 60 insertions(+), 1 deletion(-) diff --git a/src/animation/circle.rs b/src/animation/circle.rs index 7e9eff8..d41c018 100644 --- a/src/animation/circle.rs +++ b/src/animation/circle.rs @@ -4,6 +4,7 @@ use crate::vec::Vector; const THICKNESS: f32 = 0.2; const FINAL_RADIUS: f32 = 1.0 + THICKNESS * 2.0; +/// An animation of an expanding circle. pub struct CircleAnimation { center: Vector, thickness: f32, diff --git a/src/animation/mod.rs b/src/animation/mod.rs index 96d570f..e7f3b2e 100644 --- a/src/animation/mod.rs +++ b/src/animation/mod.rs @@ -7,7 +7,17 @@ use crate::vec::Vector; #[cfg(test)] use mockall::automock; +/// A sampler for an animation. #[cfg_attr(test, automock)] pub trait Animation { + /// Returns the level (of brightness) for the + /// given step of the animation an position on screen. + /// # Arguments + /// * `step`: `0 <= step` and `step <= 1` + /// + /// # Return values + /// * `1 < n` => Keep current character + /// * `0 <= n` and `n < 1` => Draw some character + /// * `n < 0` => Clear character fn sample(&self, step: f32, pos: Vector) -> f32; } \ No newline at end of file diff --git a/src/animation/rhombus.rs b/src/animation/rhombus.rs index 4ac73e7..54a0507 100644 --- a/src/animation/rhombus.rs +++ b/src/animation/rhombus.rs @@ -4,6 +4,7 @@ use crate::vec::Vector; const THICKNESS: f32 = 0.2; const FINAL_DISTANCE: f32 = 1.0 + THICKNESS * 2.0; +/// An animation of an expanding rhombus. pub struct RhombusAnimation { center: Vector, thickness: f32, diff --git a/src/choose.rs b/src/choose.rs index fa82d7c..c9dff80 100644 --- a/src/choose.rs +++ b/src/choose.rs @@ -1,10 +1,13 @@ use rand::prelude::IteratorRandom; use rand::Rng; +/// A trait to get all values of an enum. pub trait Collection { + /// Returns a list of all enum values. fn all() -> Vec where Self: Sized; } +/// Choose a enum from a list of options. pub struct Chooser { rng: TRng } @@ -14,6 +17,8 @@ impl Chooser { Self { rng } } + /// Choose an enum item from the provided [Vec]. + /// If none are provided, a random one of all enum values is chosen. pub fn choose(&mut self, selection: Vec) -> TValue { let options = if selection.is_empty() { TValue::all() diff --git a/src/color.rs b/src/color.rs index 3c15fbf..130fd66 100644 --- a/src/color.rs +++ b/src/color.rs @@ -12,6 +12,7 @@ pub trait ColorSampler { fn sample(&self, fill: f32) -> Color; } +/// A simple color sampler which interpolates the color from a [Vec]. pub struct SimpleColorSampler { values: Vec } diff --git a/src/fill/circle.rs b/src/fill/circle.rs index d25acc2..513e0db 100644 --- a/src/fill/circle.rs +++ b/src/fill/circle.rs @@ -3,6 +3,7 @@ use crate::vec::Vector; const INTERVAL: f32 = 4.0; +/// Fill based on rings of a circle. pub struct CircleFillMode { center: Vector, interval: f32 diff --git a/src/fill/level.rs b/src/fill/level.rs index 414731a..394ae18 100644 --- a/src/fill/level.rs +++ b/src/fill/level.rs @@ -1,6 +1,7 @@ use crate::fill::FillMode; use crate::vec::Vector; +/// Fill based on the level of brightness. pub struct LevelFillMode; impl LevelFillMode { diff --git a/src/fill/mod.rs b/src/fill/mod.rs index dc8b7bd..d3cf5d5 100644 --- a/src/fill/mod.rs +++ b/src/fill/mod.rs @@ -11,5 +11,7 @@ use mockall::automock; #[cfg_attr(test, automock)] pub trait FillMode { /// Gets the color for this character. + /// # Arguments + /// * `step`: `0 <= step` and `step <= 1` fn sample(&self, level: f32, pos: Vector) -> f32; } \ No newline at end of file diff --git a/src/fill/stripes.rs b/src/fill/stripes.rs index 1f2f090..c50c3e6 100644 --- a/src/fill/stripes.rs +++ b/src/fill/stripes.rs @@ -3,6 +3,7 @@ use crate::vec::Vector; const INTERVAL: f32 = 4.0; +/// Fill based on diagonal stripes. pub struct StripesFillMode { interval: f32 } diff --git a/src/main.rs b/src/main.rs index cd5c6d3..6d2a2e0 100644 --- a/src/main.rs +++ b/src/main.rs @@ -35,6 +35,7 @@ mod timer; mod runner; mod choose; +/// Defines an enum and implements the [Collection] trait. macro_rules! options { ($name:ident { $($opt:ident,)* }) => { #[derive(Copy, Clone, ArgEnum)] @@ -74,6 +75,7 @@ options!(FillModeType { const MAX_FPS: u64 = 480; +/// The program arguments. #[derive(Parser)] #[clap(author = env ! ("CARGO_PKG_AUTHORS"), version = env ! ("CARGO_PKG_VERSION"), about = env ! ("CARGO_PKG_DESCRIPTION"))] struct Args { @@ -119,6 +121,7 @@ fn main() -> Result<(), Error> { runner.run() } +/// Validates the chars argument. fn validate_chars(text: &str) -> Result { if text.is_empty() { Err(anyhow!("can't be empty.")) @@ -127,6 +130,7 @@ fn validate_chars(text: &str) -> Result { } } +/// Validates the fps argument. fn validate_fps(text: &str) -> Result { let value = text.parse()?; @@ -139,6 +143,7 @@ fn validate_fps(text: &str) -> Result { } } +/// Validates the duration argument. fn validate_duration(text: &str) -> Result { let value = text.parse()?; @@ -149,12 +154,14 @@ fn validate_duration(text: &str) -> Result { } } +/// Returns the size to use based on the terminal size and width and height arguments. fn size(terminal: (u16, u16), width: Option, height: Option) -> (usize, usize) { let width = width.unwrap_or(terminal.0 as usize); let height = height.unwrap_or(terminal.1 as usize); (width, height) } +/// Calculates the delay between frames based on the fps. fn delay_of_fps(fps: u64) -> Duration { Duration::from_nanos(1_000_000_000 / fps) } diff --git a/src/render.rs b/src/render.rs index bc05224..d0b922f 100644 --- a/src/render.rs +++ b/src/render.rs @@ -6,12 +6,17 @@ use crate::Vector; #[cfg(test)] use mockall::automock; +/// A trait for anything which performs some rendering. #[cfg_attr(test, automock)] pub trait Renderer { + /// Render the frame. fn render(&mut self, step: f32); + + /// Present the finished frame. fn present(&mut self) -> Result<(), Error>; } +/// Fills its [Surface] with the values received from a [Sampler]. pub struct SamplerRenderer { surface: TSurface, sampler: TSampler, diff --git a/src/runner.rs b/src/runner.rs index ce26536..34755f6 100644 --- a/src/runner.rs +++ b/src/runner.rs @@ -3,6 +3,7 @@ use anyhow::Error; use crate::Renderer; use crate::timer::Timer; +/// Periodically calls [Renderer::render] and [Renderer::present]. pub struct Runner { timer: TTimer, ticks: u128, diff --git a/src/sampler.rs b/src/sampler.rs index 20efaac..4712233 100644 --- a/src/sampler.rs +++ b/src/sampler.rs @@ -8,17 +8,23 @@ use crate::vec::Vector; #[cfg(test)] use mockall::automock; +/// The action to perform for the given values. pub enum Sample { Keep, Draw { char: char, color: Color }, Clear, } +/// Provides a [Sample] for some values. #[cfg_attr(test, automock)] pub trait Sampler { + /// Get a [Sample] for the step of the animation and position on screen. + /// # Arguments + /// * `step`: `0 <= step` and `step <= 1` fn sample(&self, step: f32, pos: Vector) -> Sample; } +/// Links primitive samplers into a full [Sampler]. pub struct ComposedSampler { animation: Box, fill: Box, diff --git a/src/surface.rs b/src/surface.rs index aa719ba..17af0ca 100644 --- a/src/surface.rs +++ b/src/surface.rs @@ -9,21 +9,28 @@ use crate::array::Array2D; #[cfg(test)] use mockall::automock; +/// A surface to draw characters on. #[cfg_attr(test, automock)] pub trait Surface { fn width(&self) -> usize; fn height(&self) -> usize; + + /// Overwrite the character on screen with this value. fn draw(&mut self, x: usize, y: usize, char: char, color: Color); + + /// Clear the character on screen. fn clear(&mut self, x: usize, y: usize); + + /// Present the finished frame. fn present(&mut self) -> Result<(), Error>; } +/// Renders the frames into a [Write] struct. pub struct WriteSurface { out: T, array: Array2D, } - #[derive(Copy, Clone)] enum Cell { Keep, diff --git a/src/timer.rs b/src/timer.rs index fba3903..387dd5b 100644 --- a/src/timer.rs +++ b/src/timer.rs @@ -4,13 +4,17 @@ use std::time::{Duration, Instant}; #[cfg(test)] use mockall::automock; +/// Allows for periodic execution of code. #[cfg_attr(test, automock)] pub trait Timer { + /// Sleep until the next tick starts. fn sleep(&mut self); + /// Get the delay between ticks. fn delay(&self) -> Duration; } +/// A simple [Timer] based on the system clock. pub struct SimpleTimer { delay: Duration, last: Instant diff --git a/src/vec.rs b/src/vec.rs index d4a317a..a8e8e25 100644 --- a/src/vec.rs +++ b/src/vec.rs @@ -12,26 +12,32 @@ impl Vector { Self { x, y } } + /// Returns the halfway point. pub fn center(self) -> Self { Self::new(self.x / 2.0, self.y / 2.0) } + /// Returns the length. pub fn length(self) -> f32 { (self.x * self.x + self.y * self.y).sqrt() } + /// Returns the angle. pub fn angle(self) -> f32 { self.x.atan2(self.y) } + /// Returns the value of the smaller axis. pub fn smaller(self) -> f32 { self.x.min(self.y) } + /// Converts all axis into positive values. pub fn abs(self) -> Vector { Self::new(self.x.abs(), self.y.abs()) } + /// Returns the sum of all axis. pub fn sum(self) -> f32 { self.x + self.y }