feat: documentation improvements (#884)

src/geometry/mod.rs

@@ -74,33 +74,61 @@ bitflags::bitflags! {
 
 #[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
 #[derive(Copy, Clone, Hash, Debug)]
-/// Events occurring when two colliders start or stop colliding
+/// Events triggered when two colliders start or stop touching.
+///
+/// Receive these through an [`EventHandler`](crate::pipeline::EventHandler) implementation.
+/// At least one collider must have [`ActiveEvents::COLLISION_EVENTS`](crate::pipeline::ActiveEvents::COLLISION_EVENTS) enabled.
+///
+/// Use for:
+/// - Trigger zones (player entered/exited area)
+/// - Collectible items (player touched coin)
+/// - Sound effects (objects started colliding)
+/// - Game logic based on contact state
+///
+/// # Example
+/// ```
+/// # use rapier3d::prelude::*;
+/// # let h1 = ColliderHandle::from_raw_parts(0, 0);
+/// # let h2 = ColliderHandle::from_raw_parts(1, 0);
+/// # let event = CollisionEvent::Started(h1, h2, CollisionEventFlags::empty());
+/// match event {
+///     CollisionEvent::Started(h1, h2, flags) => {
+///         println!("Colliders {:?} and {:?} started touching", h1, h2);
+///         if flags.contains(CollisionEventFlags::SENSOR) {
+///             println!("At least one is a sensor!");
+///         }
+///     }
+///     CollisionEvent::Stopped(h1, h2, _) => {
+///         println!("Colliders {:?} and {:?} stopped touching", h1, h2);
+///     }
+/// }
+/// ```
 pub enum CollisionEvent {
-    /// Event occurring when two colliders start colliding
+    /// Two colliders just started touching this frame.
     Started(ColliderHandle, ColliderHandle, CollisionEventFlags),
-    /// Event occurring when two colliders stop colliding.
+    /// Two colliders just stopped touching this frame.
     Stopped(ColliderHandle, ColliderHandle, CollisionEventFlags),
 }
 
 impl CollisionEvent {
-    /// Is this a `Started` collision event?
+    /// Returns `true` if this is a Started event (colliders began touching).
     pub fn started(self) -> bool {
         matches!(self, CollisionEvent::Started(..))
     }
 
-    /// Is this a `Stopped` collision event?
+    /// Returns `true` if this is a Stopped event (colliders stopped touching).
     pub fn stopped(self) -> bool {
         matches!(self, CollisionEvent::Stopped(..))
     }
 
-    /// The handle of the first collider involved in this collision event.
+    /// Returns the handle of the first collider in this collision.
     pub fn collider1(self) -> ColliderHandle {
         match self {
             Self::Started(h, _, _) | Self::Stopped(h, _, _) => h,
         }
     }
 
-    /// The handle of the second collider involved in this collision event.
+    /// Returns the handle of the second collider in this collision.
     pub fn collider2(self) -> ColliderHandle {
         match self {
             Self::Started(_, h, _) | Self::Stopped(_, h, _) => h,