From dd6111dce329091ded2ecff4a40bc6b25ef09d05 Mon Sep 17 00:00:00 2001 From: Kristofers Solo Date: Wed, 25 Dec 2024 17:06:22 +0200 Subject: [PATCH] docs: fix typos --- src/builder.rs | 158 ++++++++-------- src/walls.rs | 492 ++++++++++++++++++++++++++----------------------- 2 files changed, 340 insertions(+), 310 deletions(-) diff --git a/src/builder.rs b/src/builder.rs index f62204c..be3c77b 100644 --- a/src/builder.rs +++ b/src/builder.rs @@ -24,58 +24,60 @@ pub enum MazeBuilderError { GenerationError(String), } -/// A builder pattern for creating hexagonal mazes. -/// -/// This struct provides a fluent interface for configuring and building hexagonal mazes. -/// It offers flexibility in specifying the maze size, random seed, and generation algorithm. -/// -/// # Examples -/// -/// Basic usage: -/// ```rust -/// use hexlab::prelude::*; -/// -/// let maze = MazeBuilder::new() -/// .with_radius(5) -/// .build() -/// .expect("Failed to create maze"); -/// -/// // A radius of 5 creates 61 hexagonal tiles -/// assert!(!maze.is_empty()); -/// assert_eq!(maze.len(), 91); -/// ``` -/// -/// Using a seed for reproducible results: -/// ```rust -/// use hexlab::prelude::*; -/// -/// let maze1 = MazeBuilder::new() -/// .with_radius(3) -/// .with_seed(12345) -/// .build() -/// .expect("Failed to create maze"); -/// -/// let maze2 = MazeBuilder::new() -/// .with_radius(3) -/// .with_seed(12345) -/// .build() -/// .expect("Failed to create maze"); -/// -/// // Same seed should produce identical mazes -/// assert_eq!(maze1.len(), maze2.len()); -/// assert_eq!(maze1, maze2); -/// ``` -/// -/// Specifying a custom generator: -/// ```rust -/// use hexlab::prelude::*; -/// -/// let maze = MazeBuilder::new() -/// .with_radius(7) -/// .with_generator(GeneratorType::RecursiveBacktracking) -/// .build() -/// .expect("Failed to create maze"); -/// ``` +/** +A builder pattern for creating hexagonal mazes. + +This struct provides a fluent interface for configuring and building hexagonal mazes. +It offers flexibility in specifying the maze size, random seed, and generation algorithm. + +# Examples + +Basic usage: +``` +use hexlab::prelude::*; + +let maze = MazeBuilder::new() + .with_radius(5) + .build() + .expect("Failed to create maze"); + +// A radius of 5 creates 61 hexagonal tiles +assert!(!maze.is_empty()); +assert_eq!(maze.len(), 91); +``` + +Using a seed for reproducible results: +``` +use hexlab::prelude::*; + +let maze1 = MazeBuilder::new() + .with_radius(3) + .with_seed(12345) + .build() + .expect("Failed to create maze"); + +let maze2 = MazeBuilder::new() + .with_radius(3) + .with_seed(12345) + .build() + .expect("Failed to create maze"); + +// Same seed should produce identical mazes +assert_eq!(maze1.len(), maze2.len()); +assert_eq!(maze1, maze2); +``` + +Specifying a custom generator: +``` +use hexlab::prelude::*; + +let maze = MazeBuilder::new() + .with_radius(7) + .with_generator(GeneratorType::RecursiveBacktracking) + .build() + .expect("Failed to create maze"); +``` +*/ #[allow(clippy::module_name_repetitions)] #[derive(Default)] pub struct MazeBuilder { @@ -138,31 +140,33 @@ impl MazeBuilder { self } - /// Builds the hexagonal maze based on the configured parameters. - /// - /// # Errors - /// - /// Returns [`MazeBuilderError::NoRadius`] if no radius is specified. - /// Returns [`MazeBuilderError::InvalidStartPosition`] if the start position is outside maze bounds. - /// - /// # Examples - /// - /// ```rust - /// use hexlab::prelude::*; - /// - /// // Should fail without radius - /// let result = MazeBuilder::new().build(); - /// assert!(result.is_err()); - /// - /// // Should succeed with radius - /// let result = MazeBuilder::new() - /// .with_radius(3) - /// .build(); - /// assert!(result.is_ok()); - /// - /// let maze = result.unwrap(); - /// assert!(!maze.is_empty()); - /// ``` + /** + Builds the hexagonal maze based on the configured parameters. + + # Errors + + Returns [`MazeBuilderError::NoRadius`] if no radius is specified. + Returns [`MazeBuilderError::InvalidStartPosition`] if the start position is outside maze bounds. + + # Examples + + ``` + use hexlab::prelude::*; + + // Should fail without radius + let result = MazeBuilder::new().build(); + assert!(result.is_err()); + + // Should succeed with radius + let result = MazeBuilder::new() + .with_radius(3) + .build(); + assert!(result.is_ok()); + + let maze = result.unwrap(); + assert!(!maze.is_empty()); + ``` + */ pub fn build(self) -> Result { let radius = self.radius.ok_or(MazeBuilderError::NoRadius)?; let mut maze = create_hex_maze(radius); diff --git a/src/walls.rs b/src/walls.rs index d919bfb..c4b9981 100644 --- a/src/walls.rs +++ b/src/walls.rs @@ -2,46 +2,48 @@ use bevy::prelude::*; use hexx::EdgeDirection; -/// A bit-flag representation of walls in a hexagonal tile. -/// -/// `Walls` uses an efficient bit-flag system to track the presence or absence of walls -/// along each edge of a hexagonal tile. Each of the six possible walls is represented -/// by a single bit in an 8-bit integer, allowing for fast operations and minimal memory usage. -/// -/// # Examples -/// -/// Creating and manipulating walls: -/// ```rust -/// use hexlab::prelude::*; -/// -/// // Create a hexagon with all walls -/// let walls = Walls::new(); -/// assert!(walls.is_closed()); -/// -/// // Create a hexagon with no walls -/// let mut walls = Walls::empty(); -/// assert!(walls.is_empty()); -/// -/// // Add specific walls -/// walls.add(EdgeDirection::FLAT_NORTH); -/// walls.add(EdgeDirection::FLAT_SOUTH); -/// assert_eq!(walls.count(), 2); -/// ``` -/// -/// Using walls in game logic: -/// -/// ```rust -/// use hexlab::prelude::*; -/// let mut walls = Walls::empty(); -/// -/// // Add walls to create a corner -/// walls.add(EdgeDirection::FLAT_NORTH); -/// walls.add(EdgeDirection::FLAT_SOUTH_EAST); -/// -/// // Check if a specific direction has a wall -/// assert!(walls.contains(EdgeDirection::FLAT_NORTH)); -/// assert!(!walls.contains(EdgeDirection::FLAT_SOUTH)); -/// ``` +/** +A bit-flag representation of walls in a hexagonal tile. + +`Walls` uses an efficient bit-flag system to track the presence or absence of walls +along each edge of a hexagonal tile. Each of the six possible walls is represented +by a single bit in an 8-bit integer, allowing for fast operations and minimal memory usage. + +# Examples + +Creating and manipulating walls: +``` +use hexlab::prelude::*; + +// Create a hexagon with all walls +let walls = Walls::new(); +assert!(walls.is_closed()); + +// Create a hexagon with no walls +let mut walls = Walls::empty(); +assert!(walls.is_empty()); + +// Add specific walls +walls.add(EdgeDirection::FLAT_NORTH); +walls.add(EdgeDirection::FLAT_SOUTH); +assert_eq!(walls.count(), 2); +``` + +Using walls in game logic: + +``` +use hexlab::prelude::*; +let mut walls = Walls::empty(); + +// Add walls to create a corner +walls.add(EdgeDirection::FLAT_NORTH); +walls.add(EdgeDirection::FLAT_SOUTH_EAST); + +// Check if a specific direction has a wall +assert!(walls.contains(EdgeDirection::FLAT_NORTH)); +assert!(!walls.contains(EdgeDirection::FLAT_SOUTH)); +``` +*/ #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] #[cfg_attr(feature = "bevy_reflect", derive(Reflect))] #[cfg_attr(feature = "bevy", derive(Component))] @@ -50,81 +52,89 @@ use hexx::EdgeDirection; pub struct Walls(u8); impl Walls { - /// Creates a new set of walls with all edges closed. - /// - /// This is the default state where all six edges of the hexagon have walls. - /// - /// # Examples - /// - /// ```rust - /// use hexlab::prelude::*; - /// - /// let walls = Walls::new(); - /// assert!(walls.is_closed()); - /// assert_eq!(walls.count(), 6); - /// ``` + /** + Creates a new set of walls with all edges closed. + + This is the default state where all six edges of the hexagon have walls. + + # Examples + + ``` + use hexlab::prelude::*; + + let walls = Walls::new(); + assert!(walls.is_closed()); + assert_eq!(walls.count(), 6); + ``` + */ #[inline] #[must_use] pub fn new() -> Self { Self::default() } - /// Creates a new set of walls with no edges (completely open). - /// - /// # Examples - /// - /// ```rust - /// use hexlab::prelude::*; - /// - /// let walls = Walls::empty(); - /// assert!(walls.is_empty()); - /// assert_eq!(walls.count(), 0); - /// ``` + /** + Creates a new set of walls with no edges (completely open). + + # Examples + + ``` + use hexlab::prelude::*; + + let walls = Walls::empty(); + assert!(walls.is_empty()); + assert_eq!(walls.count(), 0); + ``` + */ #[inline] #[must_use] pub const fn empty() -> Self { Self(0) } - /// Checks if the walls are currently empty - /// - /// Returns `true` if all directions have no walls set. - /// # Examples - /// - /// ```rust - /// use hexlab::prelude::*; - /// - /// let walls = Walls::empty(); - /// assert!(walls.is_empty()); - /// - /// let walls = Walls::new(); - /// assert!(!walls.is_empty()); - /// ``` + /** + Checks if the walls are currently empty + + Returns `true` if all directions have no walls set. + # Examples + + ``` + use hexlab::prelude::*; + + let walls = Walls::empty(); + assert!(walls.is_empty()); + + let walls = Walls::new(); + assert!(!walls.is_empty()); + ``` + */ #[inline] #[must_use] pub const fn is_empty(&self) -> bool { self.0 == 0 } - /// Adds a wall in the specified direction - /// - /// This method uses bitwise operations to efficiently set the wall flag - /// for the given direction. Multiple walls can be added to the same hexagon. - /// - /// # Examples - /// - /// ```rust - /// use hexlab::prelude::*; - /// - /// let mut walls = Walls::empty(); - /// walls.add(EdgeDirection::FLAT_NORTH); - /// assert!(walls.contains(EdgeDirection::FLAT_NORTH)); - /// assert!(!walls.contains(EdgeDirection::FLAT_SOUTH)); - /// - /// walls.add(EdgeDirection::FLAT_SOUTH); - /// assert!(walls.contains(EdgeDirection::FLAT_SOUTH)); - /// assert_eq!(walls.count(), 2); - /// ``` + /** + Adds a wall in the specified direction + + This method uses bitwise operations to efficiently set the wall flag + for the given direction. Multiple walls can be added to the same hexagon. + + # Examples + + ``` + use hexlab::prelude::*; + + let mut walls = Walls::empty(); + walls.add(EdgeDirection::FLAT_NORTH); + assert!(walls.contains(EdgeDirection::FLAT_NORTH)); + assert!(!walls.contains(EdgeDirection::FLAT_SOUTH)); + + walls.add(EdgeDirection::FLAT_SOUTH); + assert!(walls.contains(EdgeDirection::FLAT_SOUTH)); + assert_eq!(walls.count(), 2); + ``` + */ #[inline] pub fn add(&mut self, direction: T) where @@ -133,23 +143,25 @@ impl Walls { self.0 |= direction.into().0; } - /// Removes a wall in the specified direction - /// - /// Returns `true` if a wall was actually removed, `false` if there was no wall - /// in the specified direction. - /// - /// # Exmaples - /// - /// ```rust - /// use hexlab::prelude::*; - /// - /// let mut walls = Walls::new(); - /// assert!(walls.remove(EdgeDirection::FLAT_NORTH)); - /// assert!(!walls.contains(EdgeDirection::FLAT_NORTH)); - /// - /// // Removing a non-existent wall returns false - /// assert!(!walls.remove(EdgeDirection::FLAT_NORTH)); - /// ``` + /** + Removes a wall in the specified direction + + Returns `true` if a wall was actually removed, `false` if there was no wall + in the specified direction. + + # Examples + + ``` + use hexlab::prelude::*; + + let mut walls = Walls::new(); + assert!(walls.remove(EdgeDirection::FLAT_NORTH)); + assert!(!walls.contains(EdgeDirection::FLAT_NORTH)); + + // Removing a non-existent wall returns false + assert!(!walls.remove(EdgeDirection::FLAT_NORTH)); + ``` + */ #[inline] pub fn remove(&mut self, direction: T) -> bool where @@ -162,21 +174,23 @@ impl Walls { was_removed } - /// Returns true if there is a wall in the specified direction - /// - /// Uses efficient bitwise operations to check for the presence of a wall. - /// - /// # Exmaples - /// - /// ```rust - /// use hexlab::prelude::*; - /// - /// let mut walls = Walls::empty(); - /// - /// walls.add(EdgeDirection::FLAT_NORTH); - /// assert!(walls.contains(EdgeDirection::FLAT_NORTH)); - /// assert!(!walls.contains(EdgeDirection::FLAT_SOUTH)); - /// ``` + /** + Returns true if there is a wall in the specified direction + + Uses efficient bitwise operations to check for the presence of a wall. + + # Examples + + ``` + use hexlab::prelude::*; + + let mut walls = Walls::empty(); + + walls.add(EdgeDirection::FLAT_NORTH); + assert!(walls.contains(EdgeDirection::FLAT_NORTH)); + assert!(!walls.contains(EdgeDirection::FLAT_SOUTH)); + ``` + */ #[inline] pub fn contains(&self, other: T) -> bool where @@ -185,90 +199,98 @@ impl Walls { self.0 & other.into().0 != 0 } - /// Returns the raw bit representation of the walls - /// - /// This method provides access to the underlying bit flags for advanced usage. - /// The bits are ordered according to the `EdgeDirection` indices. - /// - /// # Exmaples - /// - /// ```rust - /// use hexlab::prelude::*; - /// - /// let mut walls = Walls::new(); - /// - /// assert_eq!(walls.as_bits(), 0b111111); - /// ``` + /** + Returns the raw bit representation of the walls + + This method provides access to the underlying bit flags for advanced usage. + The bits are ordered according to the `EdgeDirection` indices. + + # Examples + + ``` + use hexlab::prelude::*; + + let mut walls = Walls::new(); + + assert_eq!(walls.as_bits(), 0b111111); + ``` + */ #[inline] #[must_use] pub const fn as_bits(&self) -> u8 { self.0 } - /// Returns the total number of walls present - /// - /// Efficiently counts the number of set bits in the internal representation. - /// - /// # Exmaples - /// - /// ```rust - /// use hexlab::prelude::*; - /// - /// let mut walls = Walls::empty(); - /// - /// assert_eq!(walls.count(), 0); - /// - /// walls.add(EdgeDirection::FLAT_NORTH); - /// walls.add(EdgeDirection::FLAT_SOUTH); - /// assert_eq!(walls.count(), 2); - /// ``` + /** + Returns the total number of walls present + + Efficiently counts the number of set bits in the internal representation. + + # Examples + + ``` + use hexlab::prelude::*; + + let mut walls = Walls::empty(); + + assert_eq!(walls.count(), 0); + + walls.add(EdgeDirection::FLAT_NORTH); + walls.add(EdgeDirection::FLAT_SOUTH); + assert_eq!(walls.count(), 2); + ``` + */ #[inline] #[must_use] pub fn count(&self) -> u8 { u8::try_from(self.0.count_ones()).unwrap_or_default() } - /// Returns all possible directions as a `Walls` value - /// - /// This represents a hexagon with walls in all six directions. - /// - /// # Exmaples - /// - /// ```rust - /// use hexlab::prelude::*; - /// - /// let all_walls = Walls::all_directions(); - /// - /// assert_eq!(all_walls.count(), 6); - /// assert!(all_walls.is_closed()); - /// ``` + /** + Returns all possible directions as a `Walls` value + + This represents a hexagon with walls in all six directions. + + # Examples + + ``` + use hexlab::prelude::*; + + let all_walls = Walls::all_directions(); + + assert_eq!(all_walls.count(), 6); + assert!(all_walls.is_closed()); + ``` + */ #[inline] #[must_use] pub const fn all_directions() -> Self { Self(0b11_1111) } - /// Toggles a wall in the specified direction. - /// - /// If a wall exists in the given direction, it will be removed. - /// If no wall exists, one will be added. - /// Returns the previous state (`true` if a wall was present). - /// - /// # Examples - /// - /// ```rust - /// use hexlab::prelude::*; - /// - /// let mut walls = Walls::empty(); - /// - /// assert!(!walls.toggle(EdgeDirection::FLAT_NORTH)); // Returns false, wall was not present - /// assert!(walls.contains(EdgeDirection::FLAT_NORTH)); // Wall is now present - /// - /// let mut walls = Walls::new(); - /// - /// assert!(walls.toggle(EdgeDirection::FLAT_NORTH)); // Returns true, wall was present - /// assert!(!walls.contains(EdgeDirection::FLAT_NORTH)); // Wall is now removed - /// ``` + /** + Toggles a wall in the specified direction. + + If a wall exists in the given direction, it will be removed. + If no wall exists, one will be added. + Returns the previous state (`true` if a wall was present). + + # Examples + + ``` + use hexlab::prelude::*; + + let mut walls = Walls::empty(); + + assert!(!walls.toggle(EdgeDirection::FLAT_NORTH)); // Returns false, wall was not present + assert!(walls.contains(EdgeDirection::FLAT_NORTH)); // Wall is now present + + let mut walls = Walls::new(); + + assert!(walls.toggle(EdgeDirection::FLAT_NORTH)); // Returns true, wall was present + assert!(!walls.contains(EdgeDirection::FLAT_NORTH)); // Wall is now removed + ``` + */ pub fn toggle(&mut self, direction: T) -> bool where T: Into + Copy, @@ -282,50 +304,54 @@ impl Walls { is_present } - /// Checks if walls are present in all six directions. - /// - /// Returns `true` if the hexagon has all possible walls, making it completely enclosed. - /// - /// # Examples - /// - /// ```rust - /// use hexlab::prelude::*; - /// - /// let walls = Walls::new(); - /// assert!(walls.is_closed()); - /// - /// let mut walls = Walls::empty(); - /// assert!(!walls.is_closed()); - /// // Add all walls manually - /// for direction in EdgeDirection::iter() { - /// walls.add(direction); - /// } - /// assert!(walls.is_closed()); - /// ``` + /** + Checks if walls are present in all six directions. + + Returns `true` if the hexagon has all possible walls, making it completely enclosed. + + # Examples + + ``` + use hexlab::prelude::*; + + let walls = Walls::new(); + assert!(walls.is_closed()); + + let mut walls = Walls::empty(); + assert!(!walls.is_closed()); + // Add all walls manually + for direction in EdgeDirection::iter() { + walls.add(direction); + } + assert!(walls.is_closed()); + ``` + */ #[inline] #[must_use] pub fn is_closed(&self) -> bool { self.count() == 6 } - /// Sets walls for multiple directions at once. - /// - /// This method efficiently adds multiple walls in a single operation while - /// preserving any existing walls not specified in the input. - /// - /// # Examples - /// - /// ```rust - /// use hexlab::prelude::*; - /// - /// let mut walls = Walls::empty(); - /// walls.add(EdgeDirection::FLAT_NORTH); - /// - /// walls.fill([EdgeDirection::FLAT_SOUTH, EdgeDirection::FLAT_SOUTH_EAST]); - /// - /// assert!(walls.contains(EdgeDirection::FLAT_SOUTH)); - /// assert_eq!(walls.count(), 3); - /// ``` + /** + Sets walls for multiple directions at once. + + This method efficiently adds multiple walls in a single operation while + preserving any existing walls not specified in the input. + + # Examples + + ``` + use hexlab::prelude::*; + + let mut walls = Walls::empty(); + walls.add(EdgeDirection::FLAT_NORTH); + + walls.fill([EdgeDirection::FLAT_SOUTH, EdgeDirection::FLAT_SOUTH_EAST]); + + assert!(walls.contains(EdgeDirection::FLAT_SOUTH)); + assert_eq!(walls.count(), 3); + ``` + */ #[inline] pub fn fill(&mut self, other: T) where