Fix intra-doc links and make CI test them (#14076)

# Objective

- Bevy currently has lot of invalid intra-doc links, let's fix them!
- Also make CI test them, to avoid future regressions.
- Helps with #1983 (but doesn't fix it, as there could still be explicit
links to docs.rs that are broken)

## Solution

- Make `cargo r -p ci -- doc-check` check fail on warnings (could also
be changed to just some specific lints)
- Manually fix all the warnings (note that in some cases it was unclear
to me what the fix should have been, I'll try to highlight them in a
self-review)

crates/bevy_app/src/app.rs

@@ -318,7 +318,7 @@ impl App {
     }
 
     /// Initializes `T` event handling by inserting an event queue resource ([`Events::<T>`])
-    /// and scheduling an [`event_update_system`] in [`First`](crate::First).
+    /// and scheduling an [`event_update_system`] in [`First`].
     ///
     /// See [`Events`] for information on how to define events.
     ///

crates/bevy_app/src/main_schedule.rs

@@ -17,7 +17,7 @@ use bevy_ecs::{
 /// Then it will run:
 /// * [`First`]
 /// * [`PreUpdate`]
-/// * [`StateTransition`](bevy_state::transition::StateTransition)
+/// * [`StateTransition`]
 /// * [`RunFixedMainLoop`]
 ///     * This will run [`FixedMain`] zero to many times, based on how much time has elapsed.
 /// * [`Update`]
@@ -32,6 +32,7 @@ use bevy_ecs::{
 ///
 /// See [`RenderPlugin`] and [`PipelinedRenderingPlugin`] for more details.
 ///
+/// [`StateTransition`]: https://docs.rs/bevy/latest/bevy/prelude/struct.StateTransition.html
 /// [`RenderPlugin`]: https://docs.rs/bevy/latest/bevy/render/struct.RenderPlugin.html
 /// [`PipelinedRenderingPlugin`]: https://docs.rs/bevy/latest/bevy/render/pipelined_rendering/struct.PipelinedRenderingPlugin.html
 /// [`SubApp`]: crate::SubApp

crates/bevy_asset/src/loader.rs

@@ -287,7 +287,7 @@ impl<A: Asset> AssetContainer for A {
     }
 }
 
-/// An error that occurs when attempting to call [`LoadContext::load_direct`]
+/// An error that occurs when attempting to call [`DirectNestedLoader::load`](crate::DirectNestedLoader::load)
 #[derive(Error, Debug)]
 #[error("Failed to load dependency {dependency:?} {error}")]
 pub struct LoadDirectError {

crates/bevy_asset/src/loader_builders.rs

@@ -28,7 +28,7 @@ impl ReaderRef<'_> {
 /// A builder for loading nested assets inside a `LoadContext`.
 ///
 /// # Lifetimes
-/// - `ctx`: the lifetime of the associated [`AssetServer`] reference
+/// - `ctx`: the lifetime of the associated [`AssetServer`](crate::AssetServer) reference
 /// - `builder`: the lifetime of the temporary builder structs
 pub struct NestedLoader<'ctx, 'builder> {
     load_context: &'builder mut LoadContext<'ctx>,
@@ -107,11 +107,14 @@ impl<'ctx, 'builder> NestedLoader<'ctx, 'builder> {
     }
 
     /// Retrieves a handle for the asset at the given path and adds that path as a dependency of the asset.
-    /// If the current context is a normal [`AssetServer::load`], an actual asset load will be kicked off immediately, which ensures the load happens
-    /// as soon as possible.
-    /// "Normal loads" kicked from within a normal Bevy App will generally configure the context to kick off loads immediately.
-    /// If the current context is configured to not load dependencies automatically (ex: [`AssetProcessor`](crate::processor::AssetProcessor)),
-    /// a load will not be kicked off automatically. It is then the calling context's responsibility to begin a load if necessary.
+    /// If the current context is a normal [`AssetServer::load`](crate::AssetServer::load), an actual asset
+    /// load will be kicked off immediately, which ensures the load happens as soon as possible.
+    /// "Normal loads" kicked from within a normal Bevy App will generally configure the context to kick off
+    /// loads immediately.
+    /// If the current context is configured to not load dependencies automatically
+    /// (ex: [`AssetProcessor`](crate::processor::AssetProcessor)),
+    /// a load will not be kicked off automatically. It is then the calling context's responsibility to begin
+    /// a load if necessary.
     pub fn load<'c, A: Asset>(self, path: impl Into<AssetPath<'c>>) -> Handle<A> {
         let path = path.into().to_owned();
         let handle = if self.load_context.should_load_dependencies {
@@ -131,7 +134,7 @@ impl<'ctx, 'builder> NestedLoader<'ctx, 'builder> {
 /// A builder for loading untyped nested assets inside a [`LoadContext`].
 ///
 /// # Lifetimes
-/// - `ctx`: the lifetime of the associated [`AssetServer`] reference
+/// - `ctx`: the lifetime of the associated [`AssetServer`](crate::AssetServer) reference
 /// - `builder`: the lifetime of the temporary builder structs
 pub struct UntypedNestedLoader<'ctx, 'builder> {
     base: NestedLoader<'ctx, 'builder>,
@@ -163,7 +166,7 @@ impl<'ctx, 'builder> UntypedNestedLoader<'ctx, 'builder> {
 /// A builder for directly loading nested assets inside a `LoadContext`.
 ///
 /// # Lifetimes
-/// - `ctx`: the lifetime of the associated [`AssetServer`] reference
+/// - `ctx`: the lifetime of the associated [`AssetServer`][crate::AssetServer] reference
 /// - `builder`: the lifetime of the temporary builder structs
 /// - `reader`: the lifetime of the [`Reader`] reference used to read the asset data
 pub struct DirectNestedLoader<'ctx, 'builder, 'reader> {
@@ -277,7 +280,7 @@ impl<'ctx: 'reader, 'builder, 'reader> DirectNestedLoader<'ctx, 'builder, 'reade
 /// A builder for directly loading untyped nested assets inside a `LoadContext`.
 ///
 /// # Lifetimes
-/// - `ctx`: the lifetime of the associated [`AssetServer`] reference
+/// - `ctx`: the lifetime of the associated [`AssetServer`](crate::AssetServer) reference
 /// - `builder`: the lifetime of the temporary builder structs
 /// - `reader`: the lifetime of the [`Reader`] reference used to read the asset data
 pub struct UntypedDirectNestedLoader<'ctx, 'builder, 'reader> {

crates/bevy_asset/src/path.rs

@@ -74,7 +74,7 @@ impl<'a> Display for AssetPath<'a> {
     }
 }
 
-/// An error that occurs when parsing a string type to create an [`AssetPath`] fails, such as during [`AssetPath::parse`] or [`AssetPath::from<'static str>`].
+/// An error that occurs when parsing a string type to create an [`AssetPath`] fails, such as during [`AssetPath::parse`].
 #[derive(Error, Debug, PartialEq, Eq)]
 pub enum ParseAssetPathError {
     /// Error that occurs when the [`AssetPath::source`] section of a path string contains the [`AssetPath::label`] delimiter `#`. E.g. `bad#source://file.test`.

crates/bevy_color/src/color.rs

@@ -17,7 +17,7 @@ use bevy_reflect::prelude::*;
 /// # Operations
 ///
 /// [`Color`] supports all the standard color operations, such as [mixing](Mix),
-/// [luminance](Luminance) and [hue](Hue) adjustment, [clamping](ClampColor),
+/// [luminance](Luminance) and [hue](Hue) adjustment,
 /// and [diffing](EuclideanDistance). These operations delegate to the concrete color space contained
 /// by [`Color`], but will convert to [`Oklch`](Oklcha) for operations which aren't supported in the
 /// current space. After performing the operation, if a conversion was required, the result will be

crates/bevy_core_pipeline/src/core_3d/main_opaque_pass_3d_node.rs

@@ -17,9 +17,8 @@ use bevy_utils::tracing::info_span;
 
 use super::AlphaMask3d;
 
-/// A [`bevy_render::render_graph::Node`] that runs the [`Opaque3d`]
-/// [`BinnedRenderPhase`] and [`AlphaMask3d`]
-/// [`bevy_render::render_phase::SortedRenderPhase`]s.
+/// A [`bevy_render::render_graph::Node`] that runs the [`Opaque3d`] and [`AlphaMask3d`]
+/// [`ViewBinnedRenderPhases`]s.
 #[derive(Default)]
 pub struct MainOpaquePass3dNode;
 impl ViewNode for MainOpaquePass3dNode {

crates/bevy_core_pipeline/src/core_3d/main_transmissive_pass_3d_node.rs

@@ -14,7 +14,7 @@ use bevy_utils::tracing::info_span;
 use std::ops::Range;
 
 /// A [`bevy_render::render_graph::Node`] that runs the [`Transmissive3d`]
-/// [`SortedRenderPhase`].
+/// [`ViewSortedRenderPhases`].
 #[derive(Default)]
 pub struct MainTransmissivePass3dNode;
 

crates/bevy_core_pipeline/src/core_3d/main_transparent_pass_3d_node.rs

@@ -13,7 +13,7 @@ use bevy_render::{
 use bevy_utils::tracing::info_span;
 
 /// A [`bevy_render::render_graph::Node`] that runs the [`Transparent3d`]
-/// [`SortedRenderPhase`].
+/// [`ViewSortedRenderPhases`].
 #[derive(Default)]
 pub struct MainTransparentPass3dNode;
 

crates/bevy_core_pipeline/src/smaa/mod.rs

@@ -15,7 +15,7 @@
 //! pinch, you can simply use the default settings (via the [`Default`] trait)
 //! for a high-quality, high-performance appearance. When using SMAA, you will
 //! likely want to turn the default MSAA off by inserting the
-//! [`bevy_render::Msaa::Off`] resource into the [`App`].
+//! [`bevy_render::view::Msaa::Off`] resource into the [`App`].
 //!
 //! Those who have used SMAA in other engines should be aware that Bevy doesn't
 //! yet support the following more advanced features of SMAA:

crates/bevy_ecs/macros/src/world_query.rs

@@ -20,7 +20,7 @@ pub(crate) fn item_struct(
     user_where_clauses_with_world: Option<&WhereClause>,
 ) -> proc_macro2::TokenStream {
     let item_attrs = quote!(
-            #[doc = "Automatically generated [`WorldQuery`] item type for [`"]
+            #[doc = "Automatically generated [`WorldQuery`](#path::query::WorldQuery) item type for [`"]
             #[doc = stringify!(#struct_name)]
             #[doc = "`], returned when iterating over query results."]
             #[automatically_derived]

crates/bevy_ecs/src/entity/map_entities.rs

@@ -192,9 +192,8 @@ impl<'m> SceneEntityMapper<'m> {
     }
 
     /// Reserves the allocated references to dead entities within the world. This frees the temporary base
-    /// [`Entity`] while reserving extra generations via [`crate::entity::Entities::reserve_generations`]. Because this
-    /// renders the [`SceneEntityMapper`] unable to safely allocate any more references, this method takes ownership of
-    /// `self` in order to render it unusable.
+    /// [`Entity`] while reserving extra generations. Because this makes the [`SceneEntityMapper`] unable to
+    /// safely allocate any more references, this method takes ownership of `self` in order to render it unusable.
     pub fn finish(self, world: &mut World) {
         // SAFETY: Entities data is kept in a valid state via `EntityMap::world_scope`
         let entities = unsafe { world.entities_mut() };

crates/bevy_ecs/src/event/base.rs

@@ -26,6 +26,9 @@ use std::{
 /// [`World`]: crate::world::World
 /// [`ComponentId`]: crate::component::ComponentId
 /// [`Observer`]: crate::observer::Observer
+/// [`Events<E>`]: super::Events
+/// [`EventReader`]: super::EventReader
+/// [`EventWriter`]: super::EventWriter
 #[diagnostic::on_unimplemented(
     message = "`{Self}` is not an `Event`",
     label = "invalid `Event`",

crates/bevy_ecs/src/event/collections.rs

@@ -81,6 +81,9 @@ use std::ops::{Deref, DerefMut};
 /// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/ecs/event.rs)
 /// [Example usage standalone.](https://github.com/bevyengine/bevy/blob/latest/crates/bevy_ecs/examples/events.rs)
 ///
+/// [`EventReader`]: super::EventReader
+/// [`EventWriter`]: super::EventWriter
+/// [`event_update_system`]: super::event_update_system
 #[derive(Debug, Resource)]
 #[cfg_attr(feature = "bevy_reflect", derive(Reflect))]
 pub struct Events<E: Event> {
@@ -111,8 +114,8 @@ impl<E: Event> Events<E> {
             .min(self.events_b.start_event_count)
     }
 
-    /// "Sends" an `event` by writing it to the current event buffer. [`EventReader`]s can then read
-    /// the event.
+    /// "Sends" an `event` by writing it to the current event buffer.
+    /// [`EventReader`](super::EventReader)s can then read the event.
     /// This method returns the [ID](`EventId`) of the sent `event`.
     pub fn send(&mut self, event: E) -> EventId<E> {
         let event_id = EventId {
@@ -129,7 +132,7 @@ impl<E: Event> Events<E> {
         event_id
     }
 
-    /// Sends a list of `events` all at once, which can later be read by [`EventReader`]s.
+    /// Sends a list of `events` all at once, which can later be read by [`EventReader`](super::EventReader)s.
     /// This is more efficient than sending each event individually.
     /// This method returns the [IDs](`EventId`) of the sent `events`.
     pub fn send_batch(&mut self, events: impl IntoIterator<Item = E>) -> SendBatchIds<E> {
@@ -263,6 +266,8 @@ impl<E: Event> Events<E> {
     /// between the last `update()` call and your call to `iter_current_update_events`.
     /// If events happen outside that window, they will not be handled. For example, any events that
     /// happen after this call and before the next `update()` call will be dropped.
+    ///
+    /// [`EventReader`]: super::EventReader
     pub fn iter_current_update_events(&self) -> impl ExactSizeIterator<Item = &E> {
         self.events_b.iter().map(|i| &i.event)
     }

crates/bevy_ecs/src/event/event_cursor.rs

@@ -58,6 +58,9 @@ pub type ManualEventReader<E> = EventCursor<E>;
 ///
 /// # bevy_ecs::system::assert_is_system(send_and_receive_events);
 /// ```
+///
+/// [`EventReader`]: super::EventReader
+/// [`EventMutator`]: super::EventMutator
 #[derive(Debug)]
 pub struct EventCursor<E: Event> {
     pub(super) last_event_count: usize,
@@ -84,42 +87,42 @@ impl<E: Event> Clone for EventCursor<E> {
 
 #[allow(clippy::len_without_is_empty)] // Check fails since the is_empty implementation has a signature other than `(&self) -> bool`
 impl<E: Event> EventCursor<E> {
-    /// See [`EventReader::read`]
+    /// See [`EventReader::read`](super::EventReader::read)
     pub fn read<'a>(&'a mut self, events: &'a Events<E>) -> EventIterator<'a, E> {
         self.read_with_id(events).without_id()
     }
 
-    /// See [`EventMutator::read`]
+    /// See [`EventMutator::read`](super::EventMutator::read)
     pub fn read_mut<'a>(&'a mut self, events: &'a mut Events<E>) -> EventMutIterator<'a, E> {
         self.read_mut_with_id(events).without_id()
     }
 
-    /// See [`EventReader::read_with_id`]
+    /// See [`EventReader::read_with_id`](super::EventReader::read_with_id)
     pub fn read_with_id<'a>(&'a mut self, events: &'a Events<E>) -> EventIteratorWithId<'a, E> {
         EventIteratorWithId::new(self, events)
     }
 
-    /// See [`EventMutator::read_with_id`]
+    /// See [`EventMutator::read_with_id`](super::EventMutator::read_with_id)
     pub fn read_mut_with_id<'a>(
         &'a mut self,
         events: &'a mut Events<E>,
     ) -> EventMutIteratorWithId<'a, E> {
         EventMutIteratorWithId::new(self, events)
     }
 
-    /// See [`EventReader::par_read`]
+    /// See [`EventReader::par_read`](super::EventReader::par_read)
     #[cfg(feature = "multi_threaded")]
     pub fn par_read<'a>(&'a mut self, events: &'a Events<E>) -> EventParIter<'a, E> {
         EventParIter::new(self, events)
     }
 
-    /// See [`EventMutator::par_read`]
+    /// See [`EventMutator::par_read`](super::EventMutator::par_read)
     #[cfg(feature = "multi_threaded")]
     pub fn par_read_mut<'a>(&'a mut self, events: &'a mut Events<E>) -> EventMutParIter<'a, E> {
         EventMutParIter::new(self, events)
     }
 
-    /// See [`EventReader::len`]
+    /// See [`EventReader::len`](super::EventReader::len)
     pub fn len(&self, events: &Events<E>) -> usize {
         // The number of events in this reader is the difference between the most recent event
         // and the last event seen by it. This will be at most the number of events contained
@@ -138,12 +141,12 @@ impl<E: Event> EventCursor<E> {
             .saturating_sub(self.last_event_count)
     }
 
-    /// See [`EventReader::is_empty()`]
+    /// See [`EventReader::is_empty()`](super::EventReader::is_empty)
     pub fn is_empty(&self, events: &Events<E>) -> bool {
         self.len(events) == 0
     }
 
-    /// See [`EventReader::clear()`]
+    /// See [`EventReader::clear()`](super::EventReader::clear)
     pub fn clear(&mut self, events: &Events<E>) {
         self.last_event_count = events.event_count;
     }

crates/bevy_ecs/src/event/iterators.rs

@@ -5,7 +5,7 @@ use bevy_ecs::event::{Event, EventCursor, EventId, EventInstance, Events};
 use bevy_utils::detailed_trace;
 use std::{iter::Chain, slice::Iter};
 
-/// An iterator that yields any unread events from an [`EventReader`] or [`EventCursor`].
+/// An iterator that yields any unread events from an [`EventReader`](super::EventReader) or [`EventCursor`].
 #[derive(Debug)]
 pub struct EventIterator<'a, E: Event> {
     iter: EventIteratorWithId<'a, E>,
@@ -43,7 +43,7 @@ impl<'a, E: Event> ExactSizeIterator for EventIterator<'a, E> {
     }
 }
 
-/// An iterator that yields any unread events (and their IDs) from an [`EventReader`] or [`EventCursor`].
+/// An iterator that yields any unread events (and their IDs) from an [`EventReader`](super::EventReader) or [`EventCursor`].
 #[derive(Debug)]
 pub struct EventIteratorWithId<'a, E: Event> {
     reader: &'a mut EventCursor<E>,

crates/bevy_ecs/src/event/mut_iterators.rs

@@ -6,6 +6,8 @@ use bevy_utils::detailed_trace;
 use std::{iter::Chain, slice::IterMut};
 
 /// An iterator that yields any unread events from an [`EventMutator`] or [`EventCursor`].
+///
+/// [`EventMutator`]: super::EventMutator
 #[derive(Debug)]
 pub struct EventMutIterator<'a, E: Event> {
     iter: EventMutIteratorWithId<'a, E>,
@@ -44,6 +46,8 @@ impl<'a, E: Event> ExactSizeIterator for EventMutIterator<'a, E> {
 }
 
 /// An iterator that yields any unread events (and their IDs) from an [`EventMutator`] or [`EventCursor`].
+///
+/// [`EventMutator`]: super::EventMutator
 #[derive(Debug)]
 pub struct EventMutIteratorWithId<'a, E: Event> {
     mutator: &'a mut EventCursor<E>,

crates/bevy_ecs/src/event/mutator.rs

@@ -40,6 +40,8 @@ use bevy_ecs::{
 /// Most of the time systems will want to use [`EventMutator::read()`]. This function creates an iterator over
 /// all events that haven't been read yet by this system, marking the event as read in the process.
 ///
+/// [`EventReader`]: super::EventReader
+/// [`EventWriter`]: super::EventWriter
 #[derive(SystemParam, Debug)]
 pub struct EventMutator<'w, 's, E: Event> {
     pub(super) reader: Local<'s, EventCursor<E>>,
@@ -54,13 +56,13 @@ impl<'w, 's, E: Event> EventMutator<'w, 's, E> {
         self.reader.read_mut(&mut self.events)
     }
 
-    /// Like [`read`](Self::read), except also returning the [`EventId`] of the events.
+    /// Like [`read`](Self::read), except also returning the [`EventId`](super::EventId) of the events.
     pub fn read_with_id(&mut self) -> EventMutIteratorWithId<'_, E> {
         self.reader.read_mut_with_id(&mut self.events)
     }
 
     /// Returns a parallel iterator over the events this [`EventMutator`] has not seen yet.
-    /// See also [`for_each`](EventParIter::for_each).
+    /// See also [`for_each`](super::EventParIter::for_each).
     ///
     /// # Example
     /// ```

crates/bevy_ecs/src/event/reader.rs

@@ -12,6 +12,8 @@ use bevy_ecs::{
 ///
 /// Unlike [`EventWriter<T>`], systems with `EventReader<T>` param can be executed concurrently
 /// (but not concurrently with `EventWriter<T>` or `EventMutator<T>` systems for the same event type).
+///
+/// [`EventWriter<T>`]: super::EventWriter
 #[derive(SystemParam, Debug)]
 pub struct EventReader<'w, 's, E: Event> {
     pub(super) reader: Local<'s, EventCursor<E>>,
@@ -26,7 +28,7 @@ impl<'w, 's, E: Event> EventReader<'w, 's, E> {
         self.reader.read(&self.events)
     }
 
-    /// Like [`read`](Self::read), except also returning the [`EventId`] of the events.
+    /// Like [`read`](Self::read), except also returning the [`EventId`](super::EventId) of the events.
     pub fn read_with_id(&mut self) -> EventIteratorWithId<'_, E> {
         self.reader.read_with_id(&self.events)
     }

crates/bevy_ecs/src/event/update.rs

@@ -26,7 +26,7 @@ pub fn signal_event_update_system(signal: Option<ResMut<EventRegistry>>) {
     }
 }
 
-/// A system that calls [`Events::update`] on all registered [`Events`] in the world.
+/// A system that calls [`Events::update`](super::Events::update) on all registered [`Events`][super::Events] in the world.
 pub fn event_update_system(world: &mut World, mut last_change_tick: Local<Tick>) {
     if world.contains_resource::<EventRegistry>() {
         world.resource_scope(|world, mut registry: Mut<EventRegistry>| {

crates/bevy_ecs/src/event/writer.rs

@@ -65,15 +65,15 @@ pub struct EventWriter<'w, E: Event> {
 }
 
 impl<'w, E: Event> EventWriter<'w, E> {
-    /// Sends an `event`, which can later be read by [`EventReader`]s.
+    /// Sends an `event`, which can later be read by [`EventReader`](super::EventReader)s.
     /// This method returns the [ID](`EventId`) of the sent `event`.
     ///
     /// See [`Events`] for details.
     pub fn send(&mut self, event: E) -> EventId<E> {
         self.events.send(event)
     }
 
-    /// Sends a list of `events` all at once, which can later be read by [`EventReader`]s.
+    /// Sends a list of `events` all at once, which can later be read by [`EventReader`](super::EventReader)s.
     /// This is more efficient than sending each event individually.
     /// This method returns the [IDs](`EventId`) of the sent `events`.
     ///