Fix some cargo doc warnings + add cargo doc ci (#557)

Author: ThierryBerger

.github/workflows/main.yml

@@ -21,6 +21,18 @@ jobs:
           components: rustfmt
       - name: Check formatting
         run: cargo fmt -- --check
+  doc:
+    runs-on: ubuntu-latest
+    env:
+      RUSTDOCFLAGS: -D warnings
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          prefix-key: ${{ env.RUST_CACHE_KEY }}
+      - name: Cargo doc
+        run: cargo doc
   test:
     runs-on: ubuntu-latest
     env:

src/dynamics/rigid_body.rs

@@ -5,6 +5,9 @@ use rapier::prelude::{
 };
 use std::ops::{Add, AddAssign, Sub, SubAssign};
 
+#[cfg(doc)]
+use rapier::dynamics::IntegrationParameters;
+
 /// The Rapier handle of a [`RigidBody`] that was inserted to the physics scene.
 #[derive(Copy, Clone, Debug, Component)]
 pub struct RapierRigidBodyHandle(pub RigidBodyHandle);

src/geometry/collider.rs

@@ -12,6 +12,9 @@ use rapier::prelude::{ColliderHandle, InteractionGroups, SharedShape};
 use crate::dynamics::{CoefficientCombineRule, MassProperties};
 use crate::math::Vect;
 
+#[cfg(doc)]
+use rapier::{dynamics::RigidBody, geometry::ContactForceEvent};
+
 /// The Rapier handle of a collider that was inserted to the physics scene.
 #[derive(Copy, Clone, Debug, Component)]
 pub struct RapierColliderHandle(pub ColliderHandle);
@@ -25,8 +28,8 @@ pub struct AsyncCollider(pub ComputedColliderShape);
 #[cfg(all(feature = "dim3", feature = "async-collider"))]
 #[derive(Component, Debug, Clone)]
 pub struct AsyncSceneCollider {
-    /// Collider type for each scene mesh not included in [`named_shapes`]. If [`None`], then all
-    /// shapes will be skipped for processing except [`named_shapes`].
+    /// Collider type for each scene mesh not included in [`Self::named_shapes`]. If [`None`], then all
+    /// shapes will be skipped for processing except [`Self::named_shapes`].
     pub shape: Option<ComputedColliderShape>,
     /// Shape types for meshes by name. If shape is [`None`], then it will be skipped for
     /// processing.
@@ -103,7 +106,7 @@ impl fmt::Debug for Collider {
     }
 }
 
-/// Overwrites the default application of [`GlobalTransform::scale`] to a [`Collider`]'s shapes.
+/// Overwrites the default application of [`GlobalTransform`] scale to a [`Collider`]'s shapes.
 #[derive(Copy, Clone, Debug, PartialEq, Component, Reflect)]
 pub enum ColliderScale {
     /// This scale will be multiplied with the scale in the [`GlobalTransform`] component

src/geometry/shape_views/collider_view.rs

@@ -6,6 +6,9 @@ use rapier::geometry::{RoundShape, SharedShape};
 use rapier::parry::either::Either;
 use rapier::parry::shape::TypedShape;
 
+#[cfg(doc)]
+use rapier::parry;
+
 /// Read-only access to the properties of a collider.
 #[derive(Copy, Clone)]
 pub enum ColliderView<'a> {
@@ -160,7 +163,7 @@ impl<'a> From<ColliderView<'a>> for SharedShape {
 }
 
 impl<'a> ColliderView<'a> {
-    /// Convert to [`parry::TypedShape`].
+    /// Convert to [`parry::shape::TypedShape`].
     pub fn as_typed_shape(self) -> TypedShape<'a> {
         match self {
             ColliderView::Ball(BallView { raw: s }) => TypedShape::Ball(s),
@@ -208,7 +211,7 @@ impl<'a> ColliderView<'a> {
         }
     }
 
-    /// Convert to [`parry::SharedShape`].
+    /// Convert to [`parry::shape::SharedShape`].
     pub fn to_shared_shape(self) -> SharedShape {
         match self {
             ColliderView::Ball(BallView { raw }) => SharedShape::new(*raw),

src/pipeline/events.rs

@@ -10,7 +10,7 @@ use std::collections::HashMap;
 use std::sync::RwLock;
 
 #[cfg(doc)]
-use crate::prelude::ActiveEvents;
+use crate::prelude::{ActiveEvents, ContactForceEventThreshold};
 
 /// Events occurring when two colliders start or stop colliding
 ///
@@ -55,7 +55,7 @@ pub struct ContactForceEvent {
 // issue).
 /// A set of queues collecting events emitted by the physics engine.
 pub(crate) struct EventQueue<'a> {
-    // Used ot retrieve the entity of colliders that have been removed from the simulation
+    // Used to retrieve the entity of colliders that have been removed from the simulation
     // since the last physics step.
     pub deleted_colliders: &'a HashMap<ColliderHandle, Entity>,
     pub collision_events: RwLock<EventWriter<'a, CollisionEvent>>,

src/pipeline/query_filter.rs

@@ -4,6 +4,9 @@ pub use rapier::pipeline::QueryFilterFlags;
 
 use crate::geometry::CollisionGroups;
 
+#[cfg(doc)]
+use crate::prelude::RapierContext;
+
 /// A filter that describes what collider should be included or excluded from a scene query.
 ///
 /// For testing manually check [`RapierContext::with_query_filter`].

src/plugin/configuration.rs

@@ -3,6 +3,9 @@ use bevy::prelude::{FromWorld, Resource, World};
 use crate::math::{Real, Vect};
 use crate::plugin::RapierContext;
 
+#[cfg(doc)]
+use rapier::dynamics::IntegrationParameters;
+
 /// Difference between simulation and rendering time
 #[derive(Resource, Default)]
 pub struct SimulationToRenderTime {

src/plugin/mod.rs

@@ -1,6 +1,7 @@
 pub use self::configuration::{RapierConfiguration, SimulationToRenderTime, TimestepMode};
 pub use self::context::RapierContext;
 pub use self::plugin::{NoUserData, PhysicsSet, RapierPhysicsPlugin, RapierTransformPropagateSet};
+pub use narrow_phase::{ContactManifoldView, ContactPairView, ContactView, SolverContactView};
 
 #[allow(clippy::type_complexity)]
 #[allow(clippy::too_many_arguments)]

src/plugin/narrow_phase.rs

@@ -51,7 +51,7 @@ impl RapierContext {
     ///
     /// If this returns `None`, there is no contact between the two colliders.
     /// If this returns `Some`, then there may be a contact between the two colliders. Check the
-    /// result [`ContactPair::has_any_active_collider`] method to see if there is an actual contact.
+    /// result [`ContactPairView::has_any_active_contact`] method to see if there is an actual contact.
     pub fn contact_pair(&self, collider1: Entity, collider2: Entity) -> Option<ContactPairView> {
         let h1 = self.entity2collider.get(&collider1)?;
         let h2 = self.entity2collider.get(&collider2)?;
@@ -165,10 +165,12 @@ impl<'a> ContactManifoldView<'a> {
         self.raw.data.normal.into()
     }
 
+    /// The contacts that will be seen by the constraints solver for computing forces.
     pub fn num_solver_contacts(&self) -> usize {
         self.raw.data.solver_contacts.len()
     }
 
+    /// Gets the i-th solver contact.
     pub fn solver_contact(&self, i: usize) -> Option<SolverContactView> {
         self.raw
             .data

src/plugin/plugin.rs

@@ -41,7 +41,7 @@ where
         self
     }
 
-    /// Specifies whether the plugin should setup each of its [`PhysicsStages`]
+    /// Specifies whether the plugin should setup each of its [`PhysicsSet`]
     /// (`true`), or if the user will set them up later (`false`).
     ///
     /// The default value is `true`.
@@ -74,7 +74,7 @@ where
     }
 
     /// Provided for use when staging systems outside of this plugin using
-    /// [`with_system_setup(false)`](Self::with_system_setup).
+    /// [`with_default_system_setup(false)`](Self::with_default_system_setup).
     /// See [`PhysicsSet`] for a description of these systems.
     pub fn get_systems(set: PhysicsSet) -> SystemConfigs {
         match set {
@@ -134,19 +134,19 @@ impl<PhysicsHooksSystemParam> Default for RapierPhysicsPlugin<PhysicsHooksSystem
     }
 }
 
-/// [`StageLabel`] for each phase of the plugin.
+/// [`SystemSet`] for each phase of the plugin.
 #[derive(SystemSet, Debug, Hash, PartialEq, Eq, Clone)]
 pub enum PhysicsSet {
     /// This set runs the systems responsible for synchronizing (and
     /// initializing) backend data structures with current component state.
-    /// These systems typically run at the after [`CoreSet::Update`].
+    /// These systems typically run at the after [`Update`].
     SyncBackend,
     /// The systems responsible for advancing the physics simulation, and
     /// updating the internal state for scene queries.
     /// These systems typically run immediately after [`PhysicsSet::SyncBackend`].
     StepSimulation,
     /// The systems responsible for updating
-    /// [`crate::geometry::collider::CollidingEntities`] and writing
+    /// [`crate::geometry::CollidingEntities`] and writing
     /// the result of the last simulation step into our `bevy_rapier`
     /// components and the [`GlobalTransform`] component.
     /// These systems typically run immediately after [`PhysicsSet::StepSimulation`].