From eee266979c2756c0e7c1131b61806321ab6c9d0a Mon Sep 17 00:00:00 2001 From: Simon Gardling Date: Thu, 27 Mar 2025 14:53:36 -0400 Subject: [PATCH] proper doc comments --- src/agent.rs | 6 +++--- src/blur.rs | 10 +++++----- src/buffer.rs | 4 ++-- src/grid.rs | 12 ++++++------ src/imgdata.rs | 9 +++------ src/model.rs | 15 +++++++-------- src/util.rs | 2 +- 7 files changed, 27 insertions(+), 31 deletions(-) diff --git a/src/agent.rs b/src/agent.rs index fcbdad3..59d7c95 100644 --- a/src/agent.rs +++ b/src/agent.rs @@ -4,7 +4,7 @@ use rand::{seq::SliceRandom, Rng}; use std::f32::consts::TAU; use std::fmt::{Display, Formatter}; -// A single Physarum agent. The x and y positions are continuous, hence we use floating point numbers instead of integers. +/// A single Physarum agent. The x and y positions are continuous, hence we use floating point numbers instead of integers. #[derive(Debug, Clone, PartialEq)] pub struct Agent { pub x: f32, @@ -21,7 +21,7 @@ impl Display for Agent { } impl Agent { - // Construct a new agent with random parameters. + /// Construct a new agent with random parameters. pub fn new( width: usize, height: usize, @@ -39,7 +39,7 @@ impl Agent { } } - // Tick an agent + /// Tick an agent pub fn tick( &mut self, buf: &Buf, diff --git a/src/blur.rs b/src/blur.rs index 0735c7d..81f3988 100644 --- a/src/blur.rs +++ b/src/blur.rs @@ -13,7 +13,7 @@ impl Blur { } } - // Blur an image with 2 box filter passes. The result will be written to the src slice, while the buf slice is used as a scratch space. + /// Blur an image with 2 box filter passes. The result will be written to the src slice, while the buf slice is used as a scratch space. pub fn run( &mut self, src: &mut [f32], @@ -28,7 +28,7 @@ impl Blur { self.box_blur(src, buf, width, height, boxes[1], decay); } - // Approximate 1D Gaussian filter of standard deviation sigma with N box filter passes. Each element in the output array contains the radius of the box filter for the corresponding pass. + /// Approximate 1D Gaussian filter of standard deviation sigma with N box filter passes. Each element in the output array contains the radius of the box filter for the corresponding pass. fn boxes_for_gaussian(sigma: f32) -> [usize; N] { let w_ideal = (12.0 * sigma * sigma / N as f32 + 1.0).sqrt(); let mut w = w_ideal as usize; @@ -44,7 +44,7 @@ impl Blur { result } - // Perform one pass of the 2D box filter of the given radius. The result will be written to the src slice, while the buf slice is used as a scratch space. + /// Perform one pass of the 2D box filter of the given radius. The result will be written to the src slice, while the buf slice is used as a scratch space. fn box_blur( &mut self, src: &mut [f32], @@ -58,7 +58,7 @@ impl Blur { self.box_blur_v(buf, src, width, height, radius, decay); } - // Perform one pass of the 1D box filter of the given radius along x axis. + /// Perform one pass of the 1D box filter of the given radius along x axis. fn box_blur_h(&mut self, src: &[f32], dst: &mut [f32], width: usize, radius: usize) { let weight = 1.0 / (2 * radius + 1) as f32; @@ -81,7 +81,7 @@ impl Blur { }) } - // Perform one pass of the 1D box filter of the given radius along y axis. Applies the decay factor to the destination buffer. + /// Perform one pass of the 1D box filter of the given radius along y axis. Applies the decay factor to the destination buffer. fn box_blur_v( &mut self, src: &[f32], diff --git a/src/buffer.rs b/src/buffer.rs index 63eef0a..cef1640 100644 --- a/src/buffer.rs +++ b/src/buffer.rs @@ -14,12 +14,12 @@ impl Buf { } } - // Truncate x and y and return a corresponding index into the data slice. + /// Truncate x and y and return a corresponding index into the data slice. const fn index(&self, x: f32, y: f32) -> usize { crate::util::index(self.width, self.height, x, y) } - // Get the buffer value at a given position. The implementation effectively treats data as periodic, hence any finite position will produce a value. + /// Get the buffer value at a given position. The implementation effectively treats data as periodic, hence any finite position will produce a value. pub fn get_buf(&self, x: f32, y: f32) -> f32 { self.buf[self.index(x, y)] } diff --git a/src/grid.rs b/src/grid.rs index 37a3b75..555e9c7 100644 --- a/src/grid.rs +++ b/src/grid.rs @@ -4,7 +4,7 @@ use rand::{distributions::Uniform, Rng}; use rayon::{iter::ParallelIterator, prelude::*}; use std::fmt::{Display, Formatter}; -// A population configuration. +/// A population configuration. #[derive(Debug, Clone, Copy)] pub struct PopulationConfig { pub sensor_distance: f32, @@ -23,7 +23,7 @@ impl Display for PopulationConfig { } impl PopulationConfig { - // Construct a random configuration. + /// Construct a random configuration. pub fn new(rng: &mut R) -> Self { PopulationConfig { sensor_distance: rng.gen_range(0.0..=64.0), @@ -53,7 +53,7 @@ pub struct Grid { } impl Grid { - // Create a new grid filled with random floats in the [0.0..1.0) range. + /// Create a new grid filled with random floats in the [0.0..1.0) range. pub fn new( width: usize, height: usize, @@ -74,18 +74,18 @@ impl Grid { } } - // Truncate x and y and return a corresponding index into the data slice. + /// Truncate x and y and return a corresponding index into the data slice. const fn index(&self, x: f32, y: f32) -> usize { crate::util::index(self.width, self.height, x, y) } - // Add a value to the grid data at a given position. + /// Add a value to the grid data at a given position. pub fn deposit(&mut self, x: f32, y: f32) { let idx = self.index(x, y); self.data[idx] += self.config.deposition_amount; } - // Diffuse grid data and apply a decay multiplier. + /// Diffuse grid data and apply a decay multiplier. pub fn diffuse(&mut self, radius: usize) { self.blur.run( &mut self.data, diff --git a/src/imgdata.rs b/src/imgdata.rs index 87f26b6..fb46cf6 100644 --- a/src/imgdata.rs +++ b/src/imgdata.rs @@ -12,7 +12,7 @@ pub struct ThinGridData { } impl ThinGridData { - // Convert Grid to ThinGridData + /// Convert Grid to ThinGridData pub fn new_from_grid(in_grid: &Grid) -> Self { ThinGridData { width: in_grid.width, @@ -22,13 +22,10 @@ impl ThinGridData { } pub fn new_from_grid_vec(in_grids: &[Grid]) -> Vec { - in_grids - .iter() - .map(Self::new_from_grid) - .collect() + in_grids.iter().map(Self::new_from_grid).collect() } - // from grid.rs (needed in image gen) + /// from grid.rs (needed in image gen) pub fn quantile(&self, fraction: f32) -> f32 { let index = if (fraction - 1.0_f32).abs() < f32::EPSILON { self.data.len() - 1 diff --git a/src/model.rs b/src/model.rs index 670b154..5a00acb 100644 --- a/src/model.rs +++ b/src/model.rs @@ -10,21 +10,21 @@ use rand_distr::{Distribution, Normal}; use rayon::{iter::ParallelIterator, prelude::*}; use std::time::Instant; -// Top-level simulation class. +/// Top-level simulation class. pub struct Model { - // per-population grid (one for each population) + /// per-population grid (one for each population) population_grids: Vec, - // Attraction table governs interaction across populations + /// Attraction table governs interaction across populations attraction_table: Vec>, - // Global grid diffusivity. + /// Global grid diffusivity. diffusivity: usize, - // Current model iteration. + /// Current model iteration. iteration: usize, - // Color palette + /// Color palette palette: Palette, time_per_agent_list: Vec, @@ -44,7 +44,7 @@ impl Model { println!("Attraction table: {:#?}", self.attraction_table); } - // Construct a new model with random initial conditions and random configuration. + /// Construct a new model with random initial conditions and random configuration. pub fn new( width: usize, height: usize, @@ -132,7 +132,6 @@ impl Model { ); } - // Accessors for rendering pub fn population_grids(&self) -> &[Grid] { &self.population_grids } diff --git a/src/util.rs b/src/util.rs index 542bf9f..1a59c55 100644 --- a/src/util.rs +++ b/src/util.rs @@ -3,7 +3,7 @@ pub fn wrap(x: f32, max: f32) -> f32 { x - max * ((x > max) as i32 as f32 - (x < 0.0_f32) as i32 as f32) } -// Truncate x and y and return a corresponding index into the data slice. +/// Truncate x and y and return a corresponding index into the data slice. #[inline] pub const fn index(width: usize, height: usize, x: f32, y: f32) -> usize { // x/y can come in negative, hence we shift them by width/height.