docs: document grid system and game screen environment (#65)

src/features/game_screen/mod.rs

@@ -1,5 +1,6 @@
 use crate::prelude::*;
 
+/// Plugin for the main game screen, managing the game loop and environment.
 pub struct GameScreenPlugin;
 
 impl Plugin for GameScreenPlugin {
@@ -9,10 +10,12 @@ impl Plugin for GameScreenPlugin {
     }
 }
 
+/// Sets up the game screen environment (e.g., background color).
 fn setup(mut clear_color: ResMut<ClearColor>) {
     *clear_color = ClearColor(Color::srgb(0.294, 0.412, 0.184));
 }
 
+/// Cleans up resources when exiting the game screen.
 fn cleanup(mut clear_color: ResMut<ClearColor>) {
     *clear_color = ClearColor(Color::srgb(0.2, 0.2, 0.2));
 }

src/features/grid/components.rs

@@ -1,18 +1,22 @@
 use super::errors::GridError;
 use crate::prelude::*;
 
+/// Component representing a single tile on the grid.
 #[derive(Component)]
 pub struct Tile {
     pub x: u32,
     pub y: u32,
 }
 
+/// Visual marker component for the crop on a tile.
 #[derive(Component)]
 pub struct CropVisual;
 
+/// Visual marker component for the water on a tile.
 #[derive(Component)]
 pub struct WaterVisual;
 
+/// The logical state of a tile.
 #[derive(Component, Default, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub enum TileState {
     #[default]
@@ -38,6 +42,7 @@ impl TileState {
     }
 }
 
+/// Resource containing grid dimensions and tile entities.
 #[derive(Resource)]
 pub struct Grid {
     pub width: u32,
@@ -46,6 +51,7 @@ pub struct Grid {
 }
 
 impl Grid {
+    /// Returns the entity of the tile at the given position.
     pub fn get_tile(&self, pos: (u32, u32)) -> Result<Entity, GridError> {
         if pos.0 >= self.width || pos.1 >= self.height {
             return Err(GridError::OutOfBounds {
@@ -56,6 +62,7 @@ impl Grid {
         Ok(self.tiles[pos.0 as usize][pos.1 as usize])
     }
 
+    /// Modifies the state of a tile using a mapping function.
     pub fn map_tile_state<F>(
         &self,
         pos: (u32, u32),
@@ -75,6 +82,7 @@ impl Grid {
         Ok(())
     }
 
+    /// Counts the number of tiles that are not unclaimed.
     pub fn count_claimed_tiles(&self, tile_query: &Query<&TileState>) -> u32 {
         self.tiles
             .iter()

src/features/grid/consts.rs

@@ -1 +1,2 @@
+/// The pixel size of a tile (width and height).
 pub const TILE_SIZE: f32 = 32.0;

src/features/grid/errors.rs

@@ -1,5 +1,6 @@
 use std::{error::Error, fmt};
 
+/// Errors related to grid operations.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum GridError {
     OutOfBounds { x: i32, y: i32 },

src/features/grid/mod.rs

@@ -7,6 +7,7 @@ pub mod consts;
 pub mod errors;
 pub mod utils;
 
+/// Manages the game grid, including tiles, visuals, and updates.
 pub struct GridPlugin;
 
 impl Plugin for GridPlugin {
@@ -18,6 +19,7 @@ impl Plugin for GridPlugin {
     }
 }
 
+/// Initializes the grid and spawns tile entities.
 fn setup(mut commands: Commands, asset_server: Res<AssetServer>, config: Res<GameConfig>) {
     let grid_width = config.grid_width;
     let grid_height = config.grid_height;
@@ -96,6 +98,7 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>, config: Res<Gam
     });
 }
 
+/// Despawns all grid entities and removes resources.
 fn cleanup(mut commands: Commands, tile_query: Query<Entity, With<Tile>>) {
     for tile_entity in tile_query.iter() {
         commands.entity(tile_entity).despawn();
@@ -103,6 +106,7 @@ fn cleanup(mut commands: Commands, tile_query: Query<Entity, With<Tile>>) {
     commands.remove_resource::<Grid>();
 }
 
+/// Updates tile visuals based on their state (e.g., crop growth, highlighting).
 fn update_tiles(
     mut query: Query<
         (&TileState, &mut AseSlice, &Children, &Tile),

src/features/grid/utils.rs

@@ -1,14 +1,17 @@
 use super::errors::GridError;
 use crate::prelude::*;
 
+/// Calculates the starting X coordinate for centering the grid.
 pub fn grid_start_x(grid_width: u32) -> f32 {
     -(grid_width as f32 * TILE_SIZE) / 2.0 + TILE_SIZE / 2.0
 }
 
+/// Calculates the starting Y coordinate for centering the grid.
 pub fn grid_start_y(grid_height: u32) -> f32 {
     -(grid_height as f32 * TILE_SIZE) / 2.0 + TILE_SIZE / 2.0
 }
 
+/// Converts world coordinates to grid coordinates.
 pub fn world_to_grid_coords(
     world_pos: Vec3,
     grid_width: u32,
@@ -30,6 +33,7 @@ pub fn world_to_grid_coords(
     Ok((x as u32, y as u32))
 }
 
+/// Converts grid coordinates to world coordinates.
 pub fn grid_to_world_coords(
     grid_x: u32,
     grid_y: u32,