[add] better documentation for all of the query code

Author: vmarcella

crates/lambda-rs-platform/src/physics/rapier2d.rs

@@ -641,6 +641,11 @@ impl PhysicsBackend2D {
 
   /// Returns all rigid bodies whose colliders contain the provided point.
   ///
+  /// This walks the live collider set instead of Rapier's query pipeline
+  /// because gameplay queries are expected to work immediately after collider
+  /// creation. Before the world steps, broad-phase acceleration structures are
+  /// not guaranteed to be synchronized with newly attached colliders.
+  ///
   /// # Arguments
   /// - `point`: The world-space point to test.
   ///
@@ -673,6 +678,12 @@ impl PhysicsBackend2D {
 
   /// Returns all rigid bodies whose colliders overlap the provided AABB.
   ///
+  /// This performs exact shape-vs-shape tests over the live collider set for
+  /// the same reason as `query_point_2d()`: overlap queries need to be correct
+  /// before the first simulation step, when broad-phase data may still be
+  /// stale. Using exact tests here also avoids broad-phase false positives in
+  /// the backend result.
+  ///
   /// # Arguments
   /// - `min`: The minimum world-space corner of the query box.
   /// - `max`: The maximum world-space corner of the query box.
@@ -695,6 +706,8 @@ impl PhysicsBackend2D {
     let mut body_slots = Vec::new();
 
     for (collider_handle, collider) in self.colliders.iter() {
+      // Express the query box in the collider's local frame because Parry's
+      // exact intersection test compares one shape pose relative to the other.
       let shape_to_collider = query_pose.inv_mul(collider.position());
       let intersects = query_dispatcher.intersection_test(
         &shape_to_collider,
@@ -721,10 +734,10 @@ impl PhysicsBackend2D {
   /// Returns the nearest rigid body hit by the provided finite ray segment.
   ///
   /// This iterates the live collider set directly instead of using Rapier's
-  /// broad-phase query pipeline. The overlap-query work already established
-  /// that direct iteration is the most reliable way to support read-only
-  /// queries immediately after collider creation, before any simulation step
-  /// has synchronized broad-phase acceleration structures.
+  /// broad-phase query pipeline because raycasts are expected to see colliders
+  /// that were just created or attached earlier in the frame. Keeping queries
+  /// on the live collider set makes the result match gameplay expectations even
+  /// before the world has advanced.
   ///
   /// # Arguments
   /// - `origin`: The world-space ray origin.

crates/lambda-rs/src/physics/mod.rs

@@ -156,6 +156,11 @@ impl PhysicsWorld2D {
 
   /// Returns all bodies whose colliders contain the provided point.
   ///
+  /// Point queries are intended for gameplay checks that can be called freely
+  /// during update code. Treating invalid floating-point input as a miss keeps
+  /// the public API simple for callers and avoids forcing game code to thread
+  /// backend validation errors through every query site.
+  ///
   /// # Arguments
   /// - `point`: The world-space point to test.
   ///
@@ -166,12 +171,22 @@ impl PhysicsWorld2D {
       return Vec::new();
     }
 
+    // Backend queries operate in collider space, but the public API reports
+    // owning bodies. Rebuild body handles and collapse duplicate hits from
+    // compound colliders before returning the result.
     let body_slots = self.backend.query_point_2d(point);
     return self.deduplicate_query_body_hits(body_slots);
   }
 
   /// Returns all bodies whose colliders overlap the provided axis-aligned box.
   ///
+  /// AABB queries are meant to be tolerant of how gameplay code produces
+  /// bounds. The world normalizes `min` and `max` before delegating so callers
+  /// can pass corners in either order without adding their own pre-processing.
+  /// Invalid floating-point inputs are treated as a miss for the same reason as
+  /// `query_point()`: query call sites stay straightforward and do not need to
+  /// handle backend-specific error types.
+  ///
   /// # Arguments
   /// - `min`: The minimum world-space corner of the query box.
   /// - `max`: The maximum world-space corner of the query box.
@@ -183,6 +198,7 @@ impl PhysicsWorld2D {
       return Vec::new();
     }
 
+    // Normalize the query box so callers do not need to sort the bounds first.
     let normalized_min = [min[0].min(max[0]), min[1].min(max[1])];
     let normalized_max = [min[0].max(max[0]), min[1].max(max[1])];
     let body_slots = self.backend.query_aabb_2d(normalized_min, normalized_max);
@@ -192,17 +208,19 @@ impl PhysicsWorld2D {
 
   /// Returns the nearest rigid body hit by the provided ray.
   ///
+  /// Raycasts are exposed as a lightweight gameplay query rather than a
+  /// fallible backend operation. Inputs that cannot represent a meaningful
+  /// finite segment are treated as a miss, and the backend hit is rebound to
+  /// this world's public body handles before returning so the high-level API
+  /// stays vendor-free.
+  ///
   /// # Arguments
   /// - `origin`: The ray origin in world space.
   /// - `dir`: The ray direction in world space.
   /// - `max_dist`: The maximum query distance.
   ///
   /// # Returns
   /// Returns the nearest hit, if one exists.
-  ///
-  /// This method preserves an infallible query contract for games: invalid
-  /// inputs return `None` instead of surfacing backend-specific validation
-  /// errors through the high-level API.
   pub fn raycast(
     &self,
     origin: [f32; 2],
@@ -245,6 +263,8 @@ impl PhysicsWorld2D {
         slot_generation,
       );
 
+      // Spatial queries match colliders internally, but the public surface is
+      // body-oriented. Compound bodies therefore collapse to one handle.
       if seen_bodies.insert(body) {
         bodies.push(body);
       }