feat: add docs

Author: sebcrozet

src/dynamics/body.rs

@@ -119,17 +119,35 @@ impl Default for BodyDesc {
     }
 }
 
+/// Coupling mode between GPU and CPU physics simulations.
+///
+/// Determines how rigid body state is synchronized between GPU and CPU representations.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Default)]
 pub enum BodyCoupling {
+    /// One-way coupling: CPU -> GPU only.
+    ///
+    /// The GPU reads body state from CPU but doesn't write back. The body is treated
+    /// as kinematic from the GPU's perspective (zero mass).
     OneWay,
+    /// Two-way coupling: CPU <-> GPU.
+    ///
+    /// The GPU both reads from and writes to the body state. The body is fully dynamic
+    /// with its mass properties applied on the GPU.
     #[default]
     TwoWays,
 }
 
+/// Associates a Rapier rigid body with a collider for GPU simulation.
+///
+/// Defines which Rapier rigid body and collider pair should be included in the
+/// GPU simulation and how they should be coupled.
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub struct BodyCouplingEntry {
+    /// Handle to the Rapier rigid body
     pub body: RigidBodyHandle,
+    /// Handle to the Rapier collider attached to this body
     pub collider: ColliderHandle,
+    /// Coupling mode (one-way or two-way synchronization)
     pub mode: BodyCoupling,
 }
 
@@ -144,6 +162,26 @@ impl<B: Backend> GpuBodySet<B> {
         self.len
     }
 
+    /// Create a GPU body set from Rapier bodies and colliders.
+    ///
+    /// Converts Rapier rigid bodies and their associated colliders into GPU-compatible
+    /// representations. The coupling entries determine which body-collider pairs are
+    /// included and how they synchronize with the CPU simulation.
+    ///
+    /// # Arguments
+    /// * `backend` - The GPU backend to allocate buffers on
+    /// * `bodies` - The Rapier rigid body set
+    /// * `colliders` - The Rapier collider set
+    /// * `coupling` - List of body-collider pairs to include with their coupling modes
+    ///
+    /// # Returns
+    /// A new `GpuBodySet` containing GPU representations of the specified bodies
+    ///
+    /// # Errors
+    /// Returns an error if GPU buffer allocation fails
+    ///
+    /// # Panics
+    /// Panics if a collider has an unsupported shape type
     pub fn from_rapier(
         backend: &B,
         bodies: &RigidBodySet,
@@ -276,18 +314,34 @@ impl<B: Backend> GpuBodySet<B> {
         &self.shapes
     }
 
+    /// GPU storage buffer containing world-space vertices for complex shapes.
+    ///
+    /// Contains vertices for polylines and trimeshes in world-space coordinates.
+    /// Updated when body poses change.
     pub fn shapes_vertex_buffers(&self) -> &GpuTensor<Point<f32>, B> {
         &self.shapes_vertex_buffers
     }
 
+    /// GPU storage buffer containing local-space vertices for complex shapes.
+    ///
+    /// Contains vertices for polylines and trimeshes in body-local coordinates.
+    /// These are the original untransformed vertices.
     pub fn shapes_local_vertex_buffers(&self) -> &GpuTensor<Point<f32>, B> {
         &self.shapes_local_vertex_buffers
     }
 
+    /// GPU storage buffer mapping each vertex to its collider ID.
+    ///
+    /// For each vertex in the vertex buffers, stores which collider (body index) it belongs to.
+    /// Used for collision detection and response.
     pub fn shapes_vertex_collider_id(&self) -> &GpuTensor<u32, B> {
         &self.shapes_vertex_collider_id
     }
 
+    /// CPU copy of shape data for all bodies.
+    ///
+    /// Returns a slice containing the [`GpuShape`] for each body in the set.
+    /// Primarily used for convenience in particle-based simulations.
     pub fn shapes_data(&self) -> &[GpuShape] {
         &self.shapes_data
     }

src/dynamics/integrate.rs

@@ -5,9 +5,9 @@ use crate::dynamics::{GpuMassProperties, GpuVelocity};
 use crate::math::GpuSim;
 use slang_hal::backend::Backend;
 use slang_hal::function::GpuFunction;
-use stensor::tensor::GpuTensor;
 use slang_hal::Shader;
 use slang_hal::ShaderArgs;
+use stensor::tensor::GpuTensor;
 
 #[derive(Shader)]
 #[shader(module = "nexus::dynamics::integrate")]

src/dynamics/mod.rs

@@ -1,6 +1,10 @@
 //! Rigid-body dynamics (forces, velocities, etc.)
 
-pub use body::{BodyDesc, GpuBodySet, GpuForce, GpuMassProperties, GpuVelocity};
+pub use body::{
+    BodyCoupling, BodyCouplingEntry, BodyDesc, GpuBodySet, GpuForce, GpuMassProperties, GpuVelocity,
+};
 
+/// Rigid body definitions and GPU body set management.
 pub mod body;
+/// Physics integration routines (position, velocity updates).
 pub mod integrate;

src/lib.rs

@@ -1,34 +1,68 @@
 #![doc = include_str!("../README.md")]
-// #![warn(missing_docs)]
+#![warn(missing_docs)]
 
 extern crate nalgebra as na;
+/// Re-export of the Rapier 2D physics engine.
+///
+/// This is available when the `dim2` feature is enabled.
 #[cfg(feature = "dim2")]
 pub extern crate rapier2d as rapier;
+/// Re-export of the Rapier 3D physics engine.
+///
+/// This is available when the `dim3` feature is enabled.
 #[cfg(feature = "dim3")]
 pub extern crate rapier3d as rapier;
 
 use slang_hal::re_exports::include_dir;
 use slang_hal::re_exports::minislang::SlangCompiler;
 
+/// GPU-accelerated rigid body dynamics simulation.
+///
+/// This module provides structures and methods for managing physics bodies
+/// on the GPU, including body state, integration, and coupling with colliders.
 pub mod dynamics;
+/// GPU-compatible shape representations.
+///
+/// This module defines shape types and utilities for converting Rapier/Parry shapes
+/// to GPU-friendly formats with vertex buffers.
 pub mod shapes;
 
+/// Mathematical types and utilities for physics simulation.
+///
+/// Re-exports Rapier's math types and defines dimension-specific type aliases
+/// for GPU simulation and angular inertia calculations.
 pub mod math {
+    /// Re-export all mathematical types from Rapier (vectors, matrices, etc.)
     pub use rapier::math::*;
 
+    /// GPU similarity transformation for 2D simulations (translation + rotation).
     #[cfg(feature = "dim2")]
     pub type GpuSim = stensor::geometry::GpuSim2;
+    /// GPU similarity transformation for 3D simulations (translation + rotation).
     #[cfg(feature = "dim3")]
     pub type GpuSim = stensor::geometry::GpuSim3;
 
+    /// Angular inertia type for 2D simulations (scalar).
     #[cfg(feature = "dim2")]
     pub type AngularInertia<N> = N;
+    /// Angular inertia type for 3D simulations (3x3 matrix).
     #[cfg(feature = "dim3")]
     pub type AngularInertia<N> = na::Matrix3<N>;
 }
 
+/// Directory containing the Slang shader source files.
+///
+/// This includes all shader code needed for GPU-accelerated physics simulation.
 pub const SLANG_SRC_DIR: include_dir::Dir<'_> =
     include_dir::include_dir!("$CARGO_MANIFEST_DIR/../../shaders");
+
+/// Register all required shaders with a Slang compiler.
+///
+/// This function registers both stensor shaders and Nexus-specific shader sources
+/// needed for GPU physics simulation.
+///
+/// # Arguments
+/// * `compiler` - The Slang compiler instance to register shaders with
 pub fn register_shaders(compiler: &mut SlangCompiler) {
     stensor::register_shaders(compiler);
     compiler.add_dir(SLANG_SRC_DIR.clone());