feat: documentation improvements (#884)

src/dynamics/joint/generic_joint.rs

@@ -115,15 +115,22 @@ impl From<JointAxis> for JointAxesMask {
     }
 }
 
-/// The limits of a joint along one of its degrees of freedom.
+/// Limits that restrict a joint's range of motion along one axis.
+///
+/// Use to constrain how far a joint can move/rotate. Examples:
+/// - Door that only opens 90°: revolute joint with limits `[0.0, PI/2.0]`
+/// - Piston with 2-unit stroke: prismatic joint with limits `[0.0, 2.0]`
+/// - Elbow that bends 0-150°: revolute joint with limits `[0.0, 5*PI/6]`
+///
+/// When a joint hits its limit, forces are applied to prevent further movement in that direction.
 #[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
 #[derive(Copy, Clone, Debug, PartialEq)]
 pub struct JointLimits<N> {
-    /// The minimum bound of the joint limit.
+    /// Minimum allowed value (angle for revolute, distance for prismatic).
     pub min: N,
-    /// The maximum bound of the joint limit.
+    /// Maximum allowed value (angle for revolute, distance for prismatic).
     pub max: N,
-    /// The impulse applied to enforce the joint’s limit.
+    /// Internal: impulse being applied to enforce the limit.
     pub impulse: N,
 }
 
@@ -147,23 +154,52 @@ impl<N: SimdRealCopy> From<[N; 2]> for JointLimits<N> {
     }
 }
 
-/// A joint’s motor along one of its degrees of freedom.
+/// A powered motor that drives a joint toward a target position/velocity.
+///
+/// Motors add actuation to joints - they apply forces to make the joint move toward
+/// a desired state. Think of them as servos, electric motors, or hydraulic actuators.
+///
+/// ## Two control modes
+///
+/// 1. **Velocity control**: Set `target_vel` to make the motor spin/slide at constant speed
+/// 2. **Position control**: Set `target_pos` with `stiffness`/`damping` to reach a target angle/position
+///
+/// You can combine both for precise control.
+///
+/// ## Parameters
+///
+/// - `stiffness`: How strongly to pull toward target (spring constant)
+/// - `damping`: Resistance to motion (prevents oscillation)
+/// - `max_force`: Maximum force/torque the motor can apply
+///
+/// # Example
+/// ```
+/// # use rapier3d::prelude::*;
+/// # use rapier3d::dynamics::{RevoluteJoint, PrismaticJoint};
+/// # let mut revolute_joint = RevoluteJoint::new(Vector::x_axis());
+/// # let mut prismatic_joint = PrismaticJoint::new(Vector::x_axis());
+/// // Motor that spins a wheel at 10 rad/s
+/// revolute_joint.set_motor_velocity(10.0, 0.8);
+///
+/// // Motor that moves to position 5.0
+/// prismatic_joint.set_motor_position(5.0, 100.0, 10.0);  // stiffness=100, damping=10
+/// ```
 #[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
 #[derive(Copy, Clone, Debug, PartialEq)]
 pub struct JointMotor {
-    /// The target velocity of the motor.
+    /// Target velocity (units/sec for prismatic, rad/sec for revolute).
     pub target_vel: Real,
-    /// The target position of the motor.
+    /// Target position (units for prismatic, radians for revolute).
     pub target_pos: Real,
-    /// The stiffness coefficient of the motor’s spring-like equation.
+    /// Spring constant - how strongly to pull toward target position.
     pub stiffness: Real,
-    /// The damping coefficient of the motor’s spring-like equation.
+    /// Damping coefficient - resistance to motion (prevents oscillation).
     pub damping: Real,
-    /// The maximum force this motor can deliver.
+    /// Maximum force the motor can apply (Newtons for prismatic, Nm for revolute).
     pub max_force: Real,
-    /// The impulse applied by this motor.
+    /// Internal: current impulse being applied.
     pub impulse: Real,
-    /// The spring-like model used for simulating this motor.
+    /// Force-based or acceleration-based motor model.
     pub model: MotorModel,
 }