docs: document many major functions, types, enums for important functionality

src/systems/collision.rs

@@ -9,6 +9,13 @@ use crate::map::builder::Map;
 use crate::systems::components::{Collider, ItemCollider, PacmanCollider};
 use crate::systems::movement::Position;
 
+/// Detects overlapping entities and generates collision events for gameplay systems.
+///
+/// Performs distance-based collision detection between Pac-Man and collectible items
+/// using each entity's position and collision radius. When entities overlap, emits
+/// a `GameEvent::Collision` for the item system to handle scoring and removal.
+/// Collision detection accounts for both entities being in motion and supports
+/// circular collision boundaries for accurate gameplay feel.
 pub fn collision_system(
     map: Res<Map>,
     pacman_query: Query<(Entity, &Position, &Collider), With<PacmanCollider>>,

src/systems/ghost.rs

@@ -14,10 +14,7 @@ use crate::{
     },
 };
 
-/// Ghost AI system that handles randomized movement decisions.
-///
-/// This system runs on all ghosts and makes periodic decisions about
-/// which direction to move in when they reach intersections.
+/// Autonomous ghost AI system implementing randomized movement with backtracking avoidance.
 pub fn ghost_movement_system(
     map: Res<Map>,
     delta_time: Res<DeltaTime>,

src/systems/movement.rs

@@ -4,7 +4,10 @@ use crate::map::graph::Graph;
 use bevy_ecs::component::Component;
 use glam::Vec2;
 
-/// A unique identifier for a node, represented by its index in the graph's storage.
+/// Zero-based index identifying a specific node in the navigation graph.
+///
+/// Nodes represent discrete movement targets in the maze. The index directly corresponds to the node's position in the
+/// graph's internal storage arrays.
 pub type NodeId = usize;
 
 /// A component that represents the speed and cardinal direction of an entity.
@@ -24,15 +27,19 @@ pub enum BufferedDirection {
     Some { direction: Direction, remaining_time: f32 },
 }
 
-/// Pure spatial position component - works for both static and dynamic entities.
+/// Entity position state that handles both stationary entities and moving entities.
+///
+/// Supports precise positioning during movement between discrete navigation nodes.
+/// When moving, entities smoothly interpolate along edges while tracking exact distance remaining to the target node.
 #[derive(Component, Debug, Copy, Clone, PartialEq)]
 pub enum Position {
-    Stopped {
-        node: NodeId,
-    },
+    /// Entity is stationary at a specific graph node.
+    Stopped { node: NodeId },
+    /// Entity is traveling between two nodes.
     Moving {
         from: NodeId,
         to: NodeId,
+        /// Distance remaining to reach the target node.
         remaining_distance: f32,
     },
 }
@@ -82,9 +89,21 @@ impl Position {
         ))
     }
 
-    /// Moves the position by a given distance towards it's current target node.
+    /// Advances movement progress by the specified distance with overflow handling.
     ///
-    /// Returns the overflow distance, if any.
+    /// For moving entities, decreases the remaining distance to the target node.
+    /// If the distance would overshoot the target, the entity transitions to
+    /// `Stopped` state and returns the excess distance for chaining movement
+    /// to the next edge in the same frame.
+    ///
+    /// # Arguments
+    ///
+    /// * `distance` - Distance to travel this frame (typically speed × delta_time)
+    ///
+    /// # Returns
+    ///
+    /// `Some(overflow)` if the target was reached with distance remaining,
+    /// `None` if still moving or already stopped.
     pub fn tick(&mut self, distance: f32) -> Option<f32> {
         if distance <= 0.0 || self.is_at_node() {
             return None;

src/systems/player.rs

@@ -17,7 +17,12 @@ use crate::{
     },
 };
 
-// Handles player input and control
+/// Processes player input commands and updates game state accordingly.
+///
+/// Handles keyboard-driven commands like movement direction changes, debug mode
+/// toggling, audio muting, and game exit requests. Movement commands are buffered
+/// to allow direction changes before reaching intersections, improving gameplay
+/// responsiveness. Non-movement commands immediately modify global game state.
 pub fn player_control_system(
     mut events: EventReader<GameEvent>,
     mut state: ResMut<GlobalState>,
@@ -69,6 +74,11 @@ fn can_traverse(entity_type: EntityType, edge: Edge) -> bool {
     edge.traversal_flags.contains(entity_flags)
 }
 
+/// Executes frame-by-frame movement for Pac-Man.
+///
+/// Handles movement logic including buffered direction changes, edge traversal validation, and continuous movement between nodes.
+/// When stopped, prioritizes buffered directions for responsive controls, falling back to current direction.
+/// Supports movement chaining within a single frame when traveling at high speeds.
 pub fn player_movement_system(
     map: Res<Map>,
     delta_time: Res<DeltaTime>,