Improve docs and heading consistency

crates/avian2d/examples/kinematic_character_2d/main.rs

@@ -11,7 +11,7 @@
 //!
 //! For a dynamic character controller, see the `dynamic_character_2d` example.
 //!
-//! ## Warning
+//! # Warning
 //!
 //! Note that this is *not* intended to be a fully featured character controller,
 //! and the collision logic is quite basic.

crates/avian2d/examples/one_way_platform_2d.rs

@@ -190,6 +190,7 @@ fn pass_through_one_way_platform(
 /// > which means you won't need to filter collisions at all.
 ///
 /// #### When an entity is known to already be passing through the [`OneWayPlatform`]
+///
 /// Any time an entity begins passing through a [`OneWayPlatform`], it is added to the
 /// [`OneWayPlatform`]'s set of currently active penetrations, and will be allowed to
 /// continue to pass through the platform until it is no longer penetrating the platform.
@@ -201,6 +202,7 @@ fn pass_through_one_way_platform(
 /// have stopped, the entity is forgotten about and the logic falls through to the next part.
 ///
 /// #### When an entity is NOT known to be passing through the [`OneWayPlatform`]
+///
 /// Depending on the setting of [`PassThroughOneWayPlatform`], the entity may be allowed to
 /// pass through.
 ///

crates/avian3d/examples/kinematic_character_3d/main.rs

@@ -12,7 +12,7 @@
 //!
 //! For a dynamic character controller, see the `dynamic_character_3d` example.
 //!
-//! ## Warning
+//! # Warning
 //!
 //! Note that this is *not* intended to be a fully featured character controller,
 //! and the collision logic is quite basic.

src/collision/collider/backend.rs

@@ -22,7 +22,7 @@ use mass_properties::OnChangeColliderMassProperties;
 ///
 /// This plugin should typically be used together with the [`ColliderHierarchyPlugin`].
 ///
-/// ## Custom collision backends
+/// # Custom Collision Backends
 ///
 /// By default, [`PhysicsPlugins`] adds this plugin for the [`Collider`] component.
 /// You can also create custom collider backends by implementing the [`AnyCollider`]

src/collision/collider/constructor.rs

@@ -18,15 +18,15 @@ use bevy::utils::HashMap;
 /// This component will only override a pre-existing [`Collider`] component on a descendant entity
 /// when it has been explicitly mentioned in the `config`.
 ///
-/// ## See also
+/// # See Also
 ///
 /// For inserting colliders on the same entity, use [`ColliderConstructor`].
 ///
-/// ## Caveats
+/// # Caveats
 ///
 /// When a component has multiple ancestors with [`ColliderConstructorHierarchy`], the insertion order is undefined.
 ///
-/// ## Example
+/// # Example
 ///
 /// ```
 #[cfg_attr(feature = "2d", doc = "use avian2d::prelude::*;")]
@@ -240,16 +240,16 @@ pub struct ColliderConstructorHierarchyConfig {
 ///
 /// This component will never override a pre-existing [`Collider`] component on the same entity.
 ///
-/// ## See also
+/// # See Also
 ///
 /// For inserting colliders on an entity's descendants, use [`ColliderConstructorHierarchy`].
 ///
-/// ## Panics
+/// # Panics
 ///
 /// The system handling the generation of colliders will panic if the specified [`ColliderConstructor`]
 /// requires a mesh, but the entity does not have a `Handle<Mesh>` component.
 ///
-/// ## Example
+/// # Example
 ///
 /// ```
 #[cfg_attr(feature = "2d", doc = "use avian2d::prelude::*;")]

src/collision/collider/mod.rs

@@ -118,7 +118,7 @@ pub trait ScalableCollider: AnyCollider {
 /// This component is added and updated automatically based on entity hierarchies and should not
 /// be modified directly.
 ///
-/// ## Example
+/// # Example
 ///
 /// ```
 #[cfg_attr(feature = "2d", doc = "use avian2d::prelude::*;")]
@@ -230,7 +230,7 @@ impl From<Transform> for ColliderTransform {
 ///
 /// Sensor colliders do *not* contribute to the mass properties of rigid bodies.
 ///
-/// ## Example
+/// # Example
 ///
 /// ```
 #[cfg_attr(feature = "2d", doc = "use avian2d::prelude::*;")]
@@ -435,7 +435,7 @@ pub struct CollisionMargin(pub Scalar);
 /// Requires the [`ContactReportingPlugin`] (included in [`PhysicsPlugins`])
 /// to be enabled for this component to be updated.
 ///
-/// ## Example
+/// # Example
 ///
 /// ```
 #[cfg_attr(feature = "2d", doc = "use avian2d::prelude::*;")]

src/collision/collider/parry/mod.rs

@@ -215,7 +215,7 @@ impl From<TrimeshFlags> for parry::shape::TriMeshFlags {
 
 /// A collider used for detecting collisions and generating contacts.
 ///
-/// ## Creation
+/// # Creation
 ///
 /// `Collider` has tons of methods for creating colliders of various shapes:
 ///
@@ -274,7 +274,7 @@ impl From<TrimeshFlags> for parry::shape::TriMeshFlags {
     doc = "Colliders can also be generated automatically for meshes and scenes. See [`ColliderConstructor`] and [`ColliderConstructorHierarchy`]."
 )]
 ///
-/// ### Multiple colliders
+/// ## Multiple Colliders
 ///
 /// It can often be useful to attach multiple colliders to the same rigid body.
 ///
@@ -332,7 +332,7 @@ impl From<TrimeshFlags> for parry::shape::TriMeshFlags {
 /// [friction](Friction), [restitution](Restitution), [collision layers](CollisionLayers),
 /// and other configuration options, and they send separate [collision events](ContactReportingPlugin#collision-events).
 ///
-/// ## See more
+/// # See More
 ///
 /// - [Rigid bodies](RigidBody)
 /// - [Density](ColliderDensity)
@@ -349,7 +349,7 @@ impl From<TrimeshFlags> for parry::shape::TriMeshFlags {
 /// - [Accessing, filtering and modifying collisions](Collisions)
 /// - [Manual contact queries](contact_query)
 ///
-/// ## Advanced usage
+/// # Advanced Usage
 ///
 /// Internally, `Collider` uses the shapes provided by `parry`. If you want to create a collider
 /// using these shapes, you can simply use `Collider::from(SharedShape::some_method())`.
@@ -561,7 +561,7 @@ impl Collider {
     ///
     /// The returned tuple is in the format `(time_of_impact, normal)`.
     ///
-    /// ## Arguments
+    /// # Arguments
     ///
     /// - `ray_origin`: Where the ray is cast from.
     /// - `ray_direction`: What direction the ray is cast in.
@@ -588,7 +588,7 @@ impl Collider {
 
     /// Tests whether the given ray intersects `self` transformed by `translation` and `rotation`.
     ///
-    /// ## Arguments
+    /// # Arguments
     ///
     /// - `ray_origin`: Where the ray is cast from.
     /// - `ray_direction`: What direction the ray is cast in.
@@ -910,7 +910,7 @@ impl Collider {
     /// The [`CollisionMargin`] component can be used to add thickness to the shape if needed.
     /// For thin shapes like triangle meshes, it can help improve collision stability and performance.
     ///
-    /// ## Example
+    /// # Example
     ///
     /// ```
     /// use avian3d::prelude::*;
@@ -944,7 +944,7 @@ impl Collider {
     /// The [`CollisionMargin`] component can be used to add thickness to the shape if needed.
     /// For thin shapes like triangle meshes, it can help improve collision stability and performance.
     ///
-    /// ## Example
+    /// # Example
     ///
     /// ```
     /// use avian3d::prelude::*;
@@ -967,7 +967,7 @@ impl Collider {
 
     /// Creates a collider with a convex polygon shape obtained from the convex hull of a `Mesh`.
     ///
-    /// ## Example
+    /// # Example
     ///
     /// ```
     /// use avian3d::prelude::*;
@@ -989,7 +989,7 @@ impl Collider {
 
     /// Creates a compound shape obtained from the decomposition of a `Mesh`.
     ///
-    /// ## Example
+    /// # Example
     ///
     /// ```
     /// use avian3d::prelude::*;
@@ -1013,7 +1013,7 @@ impl Collider {
     /// Creates a compound shape obtained from the decomposition of a `Mesh`
     /// with the given [`VhacdParameters`] passed to the decomposition algorithm.
     ///
-    /// ## Example
+    /// # Example
     ///
     /// ```
     /// use avian3d::prelude::*;

src/collision/contact_query.rs

@@ -26,7 +26,7 @@ pub type UnsupportedShape = Unsupported;
 /// Returns `None` if the colliders are separated by a distance greater than `prediction_distance`
 /// or if the given shapes are invalid.
 ///
-/// ## Example
+/// # Example
 ///
 /// ```
 /// # #[cfg(feature = "2d")]
@@ -116,7 +116,7 @@ pub fn contact(
 /// Returns an empty vector if the colliders are separated by a distance greater than `prediction_distance`
 /// or if the given shapes are invalid.
 ///
-/// ## Example
+/// # Example
 ///
 /// ```
 /// # #[cfg(feature = "2d")]
@@ -282,7 +282,7 @@ pub enum ClosestPoints {
 ///
 /// Returns `Err(UnsupportedShape)` if either of the collider shapes is not supported.
 ///
-/// ## Example
+/// # Example
 ///
 /// ```
 /// # #[cfg(feature = "2d")]
@@ -377,7 +377,7 @@ pub fn closest_points(
 /// Returns `0.0` if the colliders are touching or penetrating, and `Err(UnsupportedShape)`
 /// if either of the collider shapes is not supported.
 ///
-/// ## Example
+/// # Example
 ///
 /// ```
 /// # #[cfg(feature = "2d")]
@@ -445,7 +445,7 @@ pub fn distance(
 ///
 /// Returns `Err(UnsupportedShape)` if either of the collider shapes is not supported.
 ///
-/// ## Example
+/// # Example
 ///
 /// ```
 /// # #[cfg(feature = "2d")]
@@ -538,7 +538,7 @@ pub struct TimeOfImpact {
 /// Returns `Ok(None)` if the time of impact is greater than `max_time_of_impact`
 /// and `Err(UnsupportedShape)` if either of the collider shapes is not supported.
 ///
-/// ## Example
+/// # Example
 ///
 /// ```
 /// # #[cfg(feature = "2d")]

src/collision/contact_reporting.rs

@@ -7,7 +7,7 @@ use bevy::prelude::*;
 
 /// Sends collision events and updates [`CollidingEntities`].
 ///
-/// ## Collision events
+/// # Collision Events
 ///
 /// If the [`ContactReportingPlugin`] is enabled (the default), the following
 /// collision events are sent each frame in [`PhysicsStepSet::ReportContacts`]:
@@ -59,7 +59,7 @@ impl Plugin for ContactReportingPlugin {
 /// A [collision event](ContactReportingPlugin#collision-events)
 /// that is sent for each collision.
 ///
-/// ## Example
+/// # Example
 ///
 /// ```no_run
 #[cfg_attr(feature = "2d", doc = "use avian2d::prelude::*;")]
@@ -90,7 +90,7 @@ pub struct Collision(pub Contacts);
 /// A [collision event](ContactReportingPlugin#collision-events)
 /// that is sent when two entities start colliding.
 ///
-/// ## Example
+/// # Example
 ///
 /// ```no_run
 #[cfg_attr(feature = "2d", doc = "use avian2d::prelude::*;")]
@@ -121,7 +121,7 @@ pub struct CollisionStarted(pub Entity, pub Entity);
 /// A [collision event](ContactReportingPlugin#collision-events)
 /// that is sent when two entities stop colliding.
 ///
-/// ## Example
+/// # Example
 ///
 /// ```no_run
 #[cfg_attr(feature = "2d", doc = "use avian2d::prelude::*;")]

src/collision/layers.rs

@@ -257,7 +257,7 @@ impl Not for LayerMask {
 ///
 /// [bitmasks]: https://en.wikipedia.org/wiki/Mask_(computing)
 ///
-/// ## Creation
+/// # Creation
 ///
 /// Collision layers store memberships and filters using [`LayerMask`]s. A [`LayerMask`] can be created using
 /// bitmasks, or by creating an enum that implements [`PhysicsLayer`].
@@ -328,7 +328,7 @@ impl Not for LayerMask {
 /// }
 /// ```
 ///
-/// ## Modifying layers
+/// # Modifying Layers
 ///
 /// Existing [`CollisionLayers`] can be modified by simply accessing the `memberships` and `filters`
 /// and changing their [`LayerMask`]s.
@@ -434,7 +434,7 @@ impl Default for CollisionLayers {
 
 #[cfg(test)]
 mod tests {
-    // Needed for PhysicsLayer derive macro
+    // Needed for `PhysicsLayer` derive macro
     #[cfg(feature = "2d")]
     use crate as avian2d;
     #[cfg(feature = "3d")]

src/collision/mod.rs

@@ -49,13 +49,13 @@ use indexmap::IndexMap;
 /// Each colliding entity pair is associated with [`Contacts`] that can be accessed and modified
 /// using the various associated methods.
 ///
-/// ## Usage
+/// # Usage
 ///
 /// [`Collisions`] can be accessed at almost anytime, but for modifying and filtering collisions,
 /// it is recommended to use the [`PostProcessCollisions`] schedule. See its documentation
 /// for more information.
 ///
-/// ### Querying collisions
+/// ## Querying Collisions
 ///
 /// The following methods can be used for querying existing collisions:
 ///
@@ -68,7 +68,7 @@ use indexmap::IndexMap;
 /// The collisions can be accessed at any time, but modifications to contacts should be performed
 /// in the [`PostProcessCollisions`] schedule. Otherwise, the physics solver will use the old contact data.
 ///
-/// ### Filtering and removing collisions
+/// ## Filtering and Removing Collisions
 ///
 /// The following methods can be used for filtering or removing existing collisions:
 ///
@@ -79,7 +79,7 @@ use indexmap::IndexMap;
 /// Collision filtering and removal should be done in the [`PostProcessCollisions`] schedule.
 /// Otherwise, the physics solver will use the old contact data.
 ///
-/// ### Adding new collisions
+/// ## Adding New Collisions
 ///
 /// The following methods can be used for adding new collisions:
 ///
@@ -89,7 +89,7 @@ use indexmap::IndexMap;
 /// The most convenient place for adding new collisions is in the [`PostProcessCollisions`] schedule.
 /// Otherwise, the physics solver might not have access to them in time.
 ///
-/// ## Implementation details
+/// # Implementation Details
 ///
 /// Internally, the collisions are stored in an `IndexMap` that contains collisions from both the current frame
 /// and the previous frame, which is used for things like [collision events](ContactReportingPlugin#collision-events).

src/debug_render/configuration.rs

@@ -378,7 +378,7 @@ impl PhysicsGizmos {
 ///
 /// This overwrites the global [`PhysicsGizmos`] for this specific entity.
 ///
-/// ## Example
+/// # Example
 ///
 /// ```no_run
 #[cfg_attr(feature = "2d", doc = "use avian2d::prelude::*;")]

src/dynamics/integrator/mod.rs

@@ -98,7 +98,7 @@ pub enum IntegrationSet {
 /// You can also control how gravity affects a specific [rigid body](RigidBody) using the [`GravityScale`]
 /// component. The magnitude of the gravity will be multiplied by this scaling factor.
 ///
-/// ## Example
+/// # Example
 ///
 /// ```no_run
 #[cfg_attr(feature = "2d", doc = "use avian2d::prelude::*;")]