From 07d5b44e706694235d52b09fde481a3c01edaaca Mon Sep 17 00:00:00 2001
From: b-guild <bguildjava@gmail.com>
Date: Sun, 30 Jun 2024 15:58:48 -0700
Subject: [PATCH] Terrain comment improvements

---
 fyrox-impl/src/scene/terrain/brushstroke/mod.rs        |  2 +-
 .../src/scene/terrain/brushstroke/strokechunks.rs      | 10 +++++++++-
 fyrox-impl/src/scene/terrain/mod.rs                    |  5 +++--
 3 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/fyrox-impl/src/scene/terrain/brushstroke/mod.rs b/fyrox-impl/src/scene/terrain/brushstroke/mod.rs
index 00d7d9d58..435e34bb5 100644
--- a/fyrox-impl/src/scene/terrain/brushstroke/mod.rs
+++ b/fyrox-impl/src/scene/terrain/brushstroke/mod.rs
@@ -36,7 +36,7 @@ use std::sync::mpsc::{Receiver, SendError, Sender};
 
 pub mod brushraster;
 use brushraster::*;
-mod strokechunks;
+pub mod strokechunks;
 use strokechunks::*;
 
 /// The number of pixel messages we can accept at once before we must start processing them.
diff --git a/fyrox-impl/src/scene/terrain/brushstroke/strokechunks.rs b/fyrox-impl/src/scene/terrain/brushstroke/strokechunks.rs
index 75c61aef0..fb249a885 100644
--- a/fyrox-impl/src/scene/terrain/brushstroke/strokechunks.rs
+++ b/fyrox-impl/src/scene/terrain/brushstroke/strokechunks.rs
@@ -1,10 +1,13 @@
+//! This module manages the record of which pixels have been recently edited by a brushstroke.
+//! It stores the modified chunks and the pixels within each chunk since the last time
+//! the changes were written to the terrain's textures.
 use super::{ChunkData, StrokeData, TerrainTextureKind};
 use crate::core::algebra::Vector2;
 use crate::fxhash::{FxHashMap, FxHashSet};
 use crate::resource::texture::TextureResource;
 use crate::scene::terrain::pixel_position_to_grid_position;
 
-/// The pixels for a stroke for one chunk, generalized over the type of data being edited.
+/// The list of modified pixels in each chunk.
 #[derive(Debug, Default)]
 pub struct StrokeChunks {
     /// The size of each chunk as measured by distance from one chunk origin to the next.
@@ -16,14 +19,17 @@ pub struct StrokeChunks {
     written_pixels: FxHashMap<Vector2<i32>, FxHashSet<Vector2<u32>>>,
     /// The number of pixels written to this object.
     count: usize,
+    /// Pixel hash sets that are allocated but not currently in use
     unused_chunks: Vec<FxHashSet<Vector2<u32>>>,
 }
 
 impl StrokeChunks {
+    /// The number of modified pixels that this object is currently tracking
     #[inline]
     pub fn count(&self) -> usize {
         self.count
     }
+    /// The kind of texture being edited
     #[inline]
     pub fn kind(&self) -> TerrainTextureKind {
         self.kind
@@ -104,10 +110,12 @@ impl StrokeChunks {
             }
         }
     }
+    /// Calculates which chunk contains the given pixel position.
     #[inline]
     pub fn pixel_position_to_grid_position(&self, position: Vector2<i32>) -> Vector2<i32> {
         pixel_position_to_grid_position(position, self.chunk_size)
     }
+    /// Calculates the origin pixel position of the given chunk.
     pub fn chunk_to_origin(&self, grid_position: Vector2<i32>) -> Vector2<i32> {
         Vector2::new(
             grid_position.x * self.chunk_size.x as i32,
diff --git a/fyrox-impl/src/scene/terrain/mod.rs b/fyrox-impl/src/scene/terrain/mod.rs
index bd9148f18..ef492976d 100644
--- a/fyrox-impl/src/scene/terrain/mod.rs
+++ b/fyrox-impl/src/scene/terrain/mod.rs
@@ -625,8 +625,9 @@ pub struct TerrainRayCastResult {
 ///
 /// ## Painting
 ///
-/// Terrain has a single method for "painting" - [`Terrain::draw`], it accepts a brush with specific parameters,
-/// which can either alternate height map or a layer mask. See method's documentation for more info.
+/// Painting involves constructing a [BrushStroke] and calling its [BrushStroke::accept_messages] method with
+/// a channel receiver, and sending a series of pixel messages into that channel. The BrushStroke will translate
+/// those messages into modifications to the Terrain's textures.
 ///
 /// ## Ray casting
 ///