ci: cargo doc step (#671)

14 files changed, 189 insertions, 66 deletions

diff --git a/.github/workflows/rapier-ci-build.yml b/.github/workflows/rapier-ci-build.yml
index c38a1a5..984bb86 100644
--- a/.github/workflows/rapier-ci-build.yml
+++ b/.github/workflows/rapier-ci-build.yml
@@ -2,9 +2,9 @@ name: Rapier CI build
 
 on:
   push:
-    branches: [ master ]
+    branches: [master]
   pull_request:
-    branches: [ master ]
+    branches: [master]
 
 env:
   CARGO_TERM_COLOR: always
@@ -13,48 +13,56 @@ jobs:
   check-fmt:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-    - name: Check formatting
-      run: cargo fmt -- --check
+      - uses: actions/checkout@v4
+      - name: Check formatting
+        run: cargo fmt -- --check
+  doc:
+    runs-on: ubuntu-latest
+    env:
+      RUSTDOCFLAGS: -D warnings
+    steps:
+      - uses: actions/checkout@v4
+      - name: Cargo doc
+        run: cargo doc -p rapier3d -p rapier2d -p rapier3d-stl -p rapier3d-urdf
   build-native:
     runs-on: ubuntu-latest
     env:
       RUSTFLAGS: -D warnings
     steps:
-    - uses: actions/checkout@v4
-    - run: sudo apt-get install -y cmake libxcb-composite0-dev
-    - name: Clippy
-      run: cargo clippy
-    - name: Clippy rapier2d
-      run: cargo clippy -p rapier-examples-2d --features parallel,simd-stable
-    - name: Clippy rapier3d
-      run: cargo clippy -p rapier-examples-3d --features parallel,simd-stable
-    - name: Build rapier2d
-      run: cargo build --verbose -p rapier2d;
-    - name: Build rapier3d
-      run: cargo build --verbose -p rapier3d;
-    - name: Build rapier2d SIMD
-      run: cd crates/rapier2d; cargo build --verbose --features simd-stable;
-    - name: Build rapier3d SIMD
-      run: cd crates/rapier3d; cargo build --verbose --features simd-stable;
-    - name: Build rapier2d SIMD Parallel
-      run: cd crates/rapier2d; cargo build --verbose --features simd-stable --features parallel;
-    - name: Build rapier3d SIMD Parallel
-      run: cd crates/rapier3d; cargo build --verbose --features simd-stable --features parallel;
-    - name: Run tests
-      run: cargo test
-    - name: Check rapier_testbed2d
-      run: cargo check --verbose -p rapier_testbed2d;
-    - name: Check rapier_testbed3d
-      run: cargo check --verbose -p rapier_testbed3d;
-    - name: Check rapier_testbed2d --features parallel
-      run: cd crates/rapier_testbed2d; cargo check --verbose --features parallel;
-    - name: Check rapier_testbed3d --features parallel
-      run: cd crates/rapier_testbed3d; cargo check --verbose --features parallel;
-    - name: Check rapier-examples-2d
-      run: cargo check -j 1 --verbose -p rapier-examples-2d;
-    - name: Check rapier-examples-3d
-      run: cargo check -j 1 --verbose -p rapier-examples-3d;
+      - uses: actions/checkout@v4
+      - run: sudo apt-get install -y cmake libxcb-composite0-dev
+      - name: Clippy
+        run: cargo clippy
+      - name: Clippy rapier2d
+        run: cargo clippy -p rapier-examples-2d --features parallel,simd-stable
+      - name: Clippy rapier3d
+        run: cargo clippy -p rapier-examples-3d --features parallel,simd-stable
+      - name: Build rapier2d
+        run: cargo build --verbose -p rapier2d;
+      - name: Build rapier3d
+        run: cargo build --verbose -p rapier3d;
+      - name: Build rapier2d SIMD
+        run: cd crates/rapier2d; cargo build --verbose --features simd-stable;
+      - name: Build rapier3d SIMD
+        run: cd crates/rapier3d; cargo build --verbose --features simd-stable;
+      - name: Build rapier2d SIMD Parallel
+        run: cd crates/rapier2d; cargo build --verbose --features simd-stable --features parallel;
+      - name: Build rapier3d SIMD Parallel
+        run: cd crates/rapier3d; cargo build --verbose --features simd-stable --features parallel;
+      - name: Run tests
+        run: cargo test
+      - name: Check rapier_testbed2d
+        run: cargo check --verbose -p rapier_testbed2d;
+      - name: Check rapier_testbed3d
+        run: cargo check --verbose -p rapier_testbed3d;
+      - name: Check rapier_testbed2d --features parallel
+        run: cd crates/rapier_testbed2d; cargo check --verbose --features parallel;
+      - name: Check rapier_testbed3d --features parallel
+        run: cd crates/rapier_testbed3d; cargo check --verbose --features parallel;
+      - name: Check rapier-examples-2d
+        run: cargo check -j 1 --verbose -p rapier-examples-2d;
+      - name: Check rapier-examples-3d
+        run: cargo check -j 1 --verbose -p rapier-examples-3d;
   build-wasm:
     runs-on: ubuntu-latest
     env:
diff --git a/crates/rapier3d-urdf/src/lib.rs b/crates/rapier3d-urdf/src/lib.rs
index bad12ee..9aea453 100644
--- a/crates/rapier3d-urdf/src/lib.rs
+++ b/crates/rapier3d-urdf/src/lib.rs
@@ -43,6 +43,9 @@ use std::collections::HashMap;
 use std::path::Path;
 use xurdf::{Geometry, Inertial, Joint, Pose, Robot};
 
+#[cfg(doc)]
+use rapier3d::dynamics::Multibody;
+
 bitflags::bitflags! {
     /// Options applied to multibody joints created from the URDF joints.
     #[derive(Copy, Clone, Debug, PartialEq, Eq, Default)]
@@ -79,7 +82,7 @@ pub struct UrdfLoaderOptions {
     /// So if this option is set to `true`, it is recommended to also keep
     /// [`UrdfLoaderOptions::enable_joint_collisions`] set to `false`. If the model is then added
     /// to the physics sets using multibody joints, it is recommended to call
-    /// [`UrdfRobot::insert_with_multibody_joints`] with the [`UrdfMultibodyOptions::DISABLE_SELF_CONTACTS`]
+    /// [`UrdfRobot::insert_using_multibody_joints`] with the [`UrdfMultibodyOptions::DISABLE_SELF_CONTACTS`]
     /// flag enabled.
     pub create_colliders_from_visual_shapes: bool,
     /// If `true`, the mass properties (center-of-mass, mass, and angular inertia) read from the urdf
diff --git a/crates/rapier_testbed2d-f64/Cargo.toml b/crates/rapier_testbed2d-f64/Cargo.toml
index 8114212..0f5e201 100644
--- a/crates/rapier_testbed2d-f64/Cargo.toml
+++ b/crates/rapier_testbed2d-f64/Cargo.toml
@@ -3,9 +3,15 @@ name = "rapier_testbed2d-f64"
 version = "0.21.0"
 authors = ["Sébastien Crozet <sebcrozet@dimforge.com>"]
 description = "Testbed for the Rapier 2-dimensional physics engine in Rust."
-homepage = "http://rapier.org"
+homepage = "http://rapier.rs"
 repository = "https://github.com/dimforge/rapier"
-categories = ["science", "game-development", "mathematics", "simulation", "wasm"]
+categories = [
+    "science",
+    "game-development",
+    "mathematics",
+    "simulation",
+    "wasm",
+]
 keywords = ["physics", "dynamics", "rigid", "real-time", "impulse_joints"]
 license = "Apache-2.0"
 edition = "2021"
@@ -49,11 +55,30 @@ bevy_sprite = "0.13"
 
 # Dependencies for native only.
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
-bevy = { version = "0.13", default-features = false, features = ["bevy_asset", "bevy_winit", "x11", "tonemapping_luts", "ktx2", "zstd", "bevy_render", "bevy_pbr", "bevy_gizmos"] }
+bevy = { version = "0.13", default-features = false, features = [
+    "bevy_asset",
+    "bevy_winit",
+    "x11",
+    "tonemapping_luts",
+    "ktx2",
+    "zstd",
+    "bevy_render",
+    "bevy_pbr",
+    "bevy_gizmos",
+] }
 
 # Dependencies for WASM only.
 [target.'cfg(target_arch = "wasm32")'.dependencies]
-bevy = { version = "0.13", default-features = false, features = ["bevy_asset", "bevy_winit", "tonemapping_luts", "ktx2", "zstd", "bevy_render", "bevy_pbr", "bevy_gizmos"] }
+bevy = { version = "0.13", default-features = false, features = [
+    "bevy_asset",
+    "bevy_winit",
+    "tonemapping_luts",
+    "ktx2",
+    "zstd",
+    "bevy_render",
+    "bevy_pbr",
+    "bevy_gizmos",
+] }
 #bevy_webgl2 = "0.5"
 
 [dependencies.rapier]
diff --git a/crates/rapier_testbed2d/Cargo.toml b/crates/rapier_testbed2d/Cargo.toml
index f4672e7..ad34e56 100644
--- a/crates/rapier_testbed2d/Cargo.toml
+++ b/crates/rapier_testbed2d/Cargo.toml
@@ -3,9 +3,15 @@ name = "rapier_testbed2d"
 version = "0.21.0"
 authors = ["Sébastien Crozet <sebcrozet@dimforge.com>"]
 description = "Testbed for the Rapier 2-dimensional physics engine in Rust."
-homepage = "http://rapier.org"
+homepage = "http://rapier.rs"
 repository = "https://github.com/dimforge/rapier"
-categories = ["science", "game-development", "mathematics", "simulation", "wasm"]
+categories = [
+    "science",
+    "game-development",
+    "mathematics",
+    "simulation",
+    "wasm",
+]
 keywords = ["physics", "dynamics", "rigid", "real-time", "impulse_joints"]
 license = "Apache-2.0"
 edition = "2021"
@@ -49,11 +55,30 @@ bevy_sprite = "0.13"
 
 # Dependencies for native only.
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
-bevy = { version = "0.13", default-features = false, features = ["bevy_sprite", "bevy_winit", "x11", "tonemapping_luts", "ktx2", "zstd", "bevy_render", "bevy_pbr", "bevy_gizmos"] }
+bevy = { version = "0.13", default-features = false, features = [
+    "bevy_sprite",
+    "bevy_winit",
+    "x11",
+    "tonemapping_luts",
+    "ktx2",
+    "zstd",
+    "bevy_render",
+    "bevy_pbr",
+    "bevy_gizmos",
+] }
 
 # Dependencies for WASM only.
 [target.'cfg(target_arch = "wasm32")'.dependencies]
-bevy = { version = "0.13", default-features = false, features = ["bevy_sprite", "bevy_winit", "tonemapping_luts", "ktx2", "zstd", "bevy_render", "bevy_pbr", "bevy_gizmos"] }
+bevy = { version = "0.13", default-features = false, features = [
+    "bevy_sprite",
+    "bevy_winit",
+    "tonemapping_luts",
+    "ktx2",
+    "zstd",
+    "bevy_render",
+    "bevy_pbr",
+    "bevy_gizmos",
+] }
 #bevy_webgl2 = "0.5"
 
 [dependencies.rapier]
diff --git a/crates/rapier_testbed3d-f64/Cargo.toml b/crates/rapier_testbed3d-f64/Cargo.toml
index 8bfafed..ad2033b 100644
--- a/crates/rapier_testbed3d-f64/Cargo.toml
+++ b/crates/rapier_testbed3d-f64/Cargo.toml
@@ -3,9 +3,15 @@ name = "rapier_testbed3d-f64"
 version = "0.21.0"
 authors = ["Sébastien Crozet <sebcrozet@dimforge.com>"]
 description = "Testbed for the Rapier 3-dimensional physics engine in Rust."
-homepage = "http://rapier.org"
+homepage = "http://rapier.rs"
 repository = "https://github.com/dimforge/rapier"
-categories = ["science", "game-development", "mathematics", "simulation", "wasm"]
+categories = [
+    "science",
+    "game-development",
+    "mathematics",
+    "simulation",
+    "wasm",
+]
 keywords = ["physics", "dynamics", "rigid", "real-time", "impulse_joints"]
 license = "Apache-2.0"
 edition = "2021"
@@ -48,11 +54,28 @@ bevy_sprite = "0.13"
 
 # Dependencies for native only.
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
-bevy = { version = "0.13", default-features = false, features = ["bevy_winit", "x11", "tonemapping_luts", "ktx2", "zstd", "bevy_render", "bevy_pbr", "bevy_gizmos"] }
+bevy = { version = "0.13", default-features = false, features = [
+    "bevy_winit",
+    "x11",
+    "tonemapping_luts",
+    "ktx2",
+    "zstd",
+    "bevy_render",
+    "bevy_pbr",
+    "bevy_gizmos",
+] }
 
 # Dependencies for WASM only.
 [target.'cfg(target_arch = "wasm32")'.dependencies]
-bevy = { version = "0.13", default-features = false, features = ["bevy_winit", "tonemapping_luts", "ktx2", "zstd", "bevy_render", "bevy_pbr", "bevy_gizmos"] }
+bevy = { version = "0.13", default-features = false, features = [
+    "bevy_winit",
+    "tonemapping_luts",
+    "ktx2",
+    "zstd",
+    "bevy_render",
+    "bevy_pbr",
+    "bevy_gizmos",
+] }
 #bevy_webgl2 = "0.5"
 
 [dependencies.rapier]
diff --git a/crates/rapier_testbed3d/Cargo.toml b/crates/rapier_testbed3d/Cargo.toml
index 5623a90..56290a4 100644
--- a/crates/rapier_testbed3d/Cargo.toml
+++ b/crates/rapier_testbed3d/Cargo.toml
@@ -3,9 +3,15 @@ name = "rapier_testbed3d"
 version = "0.21.0"
 authors = ["Sébastien Crozet <sebcrozet@dimforge.com>"]
 description = "Testbed for the Rapier 3-dimensional physics engine in Rust."
-homepage = "http://rapier.org"
+homepage = "http://rapier.rs"
 repository = "https://github.com/dimforge/rapier"
-categories = ["science", "game-development", "mathematics", "simulation", "wasm"]
+categories = [
+    "science",
+    "game-development",
+    "mathematics",
+    "simulation",
+    "wasm",
+]
 keywords = ["physics", "dynamics", "rigid", "real-time", "impulse_joints"]
 license = "Apache-2.0"
 edition = "2021"
@@ -33,7 +39,7 @@ rand = "0.8"
 rand_pcg = "0.3"
 instant = { version = "0.1", features = ["web-sys", "now"] }
 bitflags = "2"
-glam = { version = "0.24", optional = true } # For Physx
+glam = { version = "0.24", optional = true }                       # For Physx
 num_cpus = { version = "1", optional = true }
 physx = { version = "0.19", features = ["glam"], optional = true }
 physx-sys = { version = "0.11", optional = true }
@@ -52,11 +58,28 @@ bevy_sprite = "0.13"
 
 # Dependencies for native only.
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
-bevy = { version = "0.13", default-features = false, features = ["bevy_winit", "x11", "tonemapping_luts", "ktx2", "zstd", "bevy_render", "bevy_pbr", "bevy_gizmos"] }
+bevy = { version = "0.13", default-features = false, features = [
+    "bevy_winit",
+    "x11",
+    "tonemapping_luts",
+    "ktx2",
+    "zstd",
+    "bevy_render",
+    "bevy_pbr",
+    "bevy_gizmos",
+] }
 
 # Dependencies for WASM only.
 [target.'cfg(target_arch = "wasm32")'.dependencies]
-bevy = { version = "0.13", default-features = false, features = ["bevy_winit", "tonemapping_luts", "ktx2", "zstd", "bevy_render", "bevy_pbr", "bevy_gizmos"] }
+bevy = { version = "0.13", default-features = false, features = [
+    "bevy_winit",
+    "tonemapping_luts",
+    "ktx2",
+    "zstd",
+    "bevy_render",
+    "bevy_pbr",
+    "bevy_gizmos",
+] }
 #bevy_webgl2 = "0.5"
 
 [dependencies.rapier]
diff --git a/src/dynamics/integration_parameters.rs b/src/dynamics/integration_parameters.rs
index f475fd4..99b6fe4 100644
--- a/src/dynamics/integration_parameters.rs
+++ b/src/dynamics/integration_parameters.rs
@@ -2,6 +2,9 @@ use crate::math::Real;
 use na::RealField;
 use std::num::NonZeroUsize;
 
+#[cfg(doc)]
+use super::RigidBodyActivation;
+
 // TODO: enabling the block solver in 3d introduces a lot of jitters in
 //       the 3D domino demo. So for now we dont enable it in 3D.
 pub(crate) static BLOCK_SOLVER_ENABLED: bool = cfg!(feature = "dim2");
@@ -66,7 +69,7 @@ pub struct IntegrationParameters {
     /// This value is used internally to estimate some length-based tolerance. In particular, the
     /// values [`IntegrationParameters::allowed_linear_error`],
     /// [`IntegrationParameters::max_corrective_velocity`],
-    /// [`IntegrationParameters::prediction_distance`], [`RigidBodyActivation::linear_threshold`]
+    /// [`IntegrationParameters::prediction_distance`], [`RigidBodyActivation::normalized_linear_threshold`]
     /// are scaled by this value implicitly.
     ///
     /// This value can be understood as the number of units-per-meter in your physical world compared
diff --git a/src/dynamics/joint/multibody_joint/multibody.rs b/src/dynamics/joint/multibody_joint/multibody.rs
index 7832abe..6859fd9 100644
--- a/src/dynamics/joint/multibody_joint/multibody.rs
+++ b/src/dynamics/joint/multibody_joint/multibody.rs
@@ -13,6 +13,9 @@ use na::{
     StorageMut, LU,
 };
 
+#[cfg(doc)]
+use crate::prelude::{GenericJoint, RigidBody};
+
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Default)]
 struct Force {
@@ -861,8 +864,7 @@ impl Multibody {
     /// Apply displacements, in generalized coordinates, to this multibody.
     ///
     /// Note this does **not** updates the link poses, only their generalized coordinates.
-    /// To update the link poses and associated rigid-bodies, call [`Self::forward_kinematics`]
-    /// or [`Self::finalize`].
+    /// To update the link poses and associated rigid-bodies, call [`Self::forward_kinematics`].
     pub fn apply_displacements(&mut self, disp: &[Real]) {
         for link in self.links.iter_mut() {
             link.joint.apply_displacement(&disp[link.assembly_id..])
diff --git a/src/dynamics/rigid_body.rs b/src/dynamics/rigid_body.rs
index 50e3211..8522d4d 100644
--- a/src/dynamics/rigid_body.rs
+++ b/src/dynamics/rigid_body.rs
@@ -10,6 +10,9 @@ use crate::math::{AngVector, Isometry, Point, Real, Rotation, Vector};
 use crate::utils::SimdCross;
 use num::Zero;
 
+#[cfg(doc)]
+use super::IntegrationParameters;
+
 #[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
 /// A rigid body.
 ///
diff --git a/src/dynamics/rigid_body_components.rs b/src/dynamics/rigid_body_components.rs
index 641434c..38ba491 100644
--- a/src/dynamics/rigid_body_components.rs
+++ b/src/dynamics/rigid_body_components.rs
@@ -10,6 +10,9 @@ use crate::parry::partitioning::IndexedData;
 use crate::utils::{SimdAngularInertia, SimdCross, SimdDot};
 use num::Zero;
 
+#[cfg(doc)]
+use super::IntegrationParameters;
+
 /// The unique handle of a rigid body added to a `RigidBodySet`.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Default)]
 #[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
diff --git a/src/geometry/collider.rs b/src/geometry/collider.rs
index d72e098..1ceab43 100644
--- a/src/geometry/collider.rs
+++ b/src/geometry/collider.rs
@@ -622,8 +622,9 @@ impl ColliderBuilder {
 
     /// Initialize a new collider builder with a capsule defined from its endpoints.
     ///
-    /// See also [`ColliderBuilder::capsule_x`], [`ColliderBuilder::capsule_y`], and
-    /// [`ColliderBuilder::capsule_z`], for a simpler way to build capsules with common
+    /// See also [`ColliderBuilder::capsule_x`], [`ColliderBuilder::capsule_y`],
+    /// (and `ColliderBuilder::capsule_z` in 3D only)
+    /// for a simpler way to build capsules with common
     /// orientations.
     pub fn capsule_from_endpoints(a: Point<Real>, b: Point<Real>, radius: Real) -> Self {
         Self::new(SharedShape::capsule(a, b, radius))
diff --git a/src/geometry/contact_pair.rs b/src/geometry/contact_pair.rs
index 8ff5dd6..3d4e955 100644
--- a/src/geometry/contact_pair.rs
+++ b/src/geometry/contact_pair.rs
@@ -7,6 +7,9 @@ use parry::query::ContactManifoldsWorkspace;
 
 use super::CollisionEvent;
 
+#[cfg(doc)]
+use super::Collider;
+
 bitflags::bitflags! {
     #[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
     #[derive(Copy, Clone, PartialEq, Eq, Debug)]
diff --git a/src/geometry/narrow_phase.rs b/src/geometry/narrow_phase.rs
index 717fa25..e979a2f 100644
--- a/src/geometry/narrow_phase.rs
+++ b/src/geometry/narrow_phase.rs
@@ -108,7 +108,7 @@ impl NarrowPhase {
 
     /// All the contacts involving the given collider.
     ///
-    /// It is strongly recommended to use the [`NarrowPhase::contacts_with`] method instead. This
+    /// It is strongly recommended to use the [`NarrowPhase::contact_pairs_with`] method instead. This
     /// method can be used if the generation number of the collider handle isn't known.
     pub fn contact_pairs_with_unknown_gen(
         &self,
@@ -141,7 +141,7 @@ impl NarrowPhase {
 
     /// All the intersection pairs involving the given collider.
     ///
-    /// It is strongly recommended to use the [`NarrowPhase::intersections_with`]  method instead.
+    /// It is strongly recommended to use the [`NarrowPhase::intersection_pairs_with`]  method instead.
     /// This method can be used if the generation number of the collider handle isn't known.
     pub fn intersection_pairs_with_unknown_gen(
         &self,
diff --git a/src/pipeline/query_pipeline/generators.rs b/src/pipeline/query_pipeline/generators.rs
index 5b86d6a..1145b4a 100644
--- a/src/pipeline/query_pipeline/generators.rs
+++ b/src/pipeline/query_pipeline/generators.rs
@@ -7,8 +7,9 @@ use crate::prelude::{Aabb, ColliderHandle, ColliderSet, RigidBodySet};
 
 #[cfg(doc)]
 use crate::{
-    dynamics::{IntegrationParameters, RigidBodyPosition},
+    dynamics::{IntegrationParameters, RigidBody, RigidBodyPosition},
     pipeline::QueryPipeline,
+    prelude::Collider,
 };
 
 /// Generates collider AABBs based on the union of their current AABB and the AABB predicted
@@ -26,7 +27,7 @@ pub struct SweptAabbWithPredictedPosition<'a> {
     pub colliders: &'a ColliderSet,
     /// The delta time to compute predicted position.
     ///
-    /// You probably want to set it to [`IntegrationParameter::dt`].
+    /// You probably want to set it to [`IntegrationParameters::dt`].
     pub dt: Real,
 }
 impl<'a> QbvhDataGenerator<ColliderHandle> for SweptAabbWithPredictedPosition<'a> {