Fix doc_markdown lints in bevy_ecs (#3473)

#3457 adds the `doc_markdown` clippy lint, which checks doc comments to make sure code identifiers are escaped with backticks. This causes a lot of lint errors, so this is one of a number of PR's that will fix those lint errors one crate at a time.

This PR fixes lints in the `bevy_ecs` crate.

Author: mfdorst

crates/bevy_ecs/src/archetype.rs

@@ -470,7 +470,7 @@ impl Archetypes {
     /// `table_components` and `sparse_set_components` must be sorted
     ///
     /// # Safety
-    /// TableId must exist in tables
+    /// [`TableId`] must exist in tables
     pub(crate) fn get_id_or_insert(
         &mut self,
         table_id: TableId,

crates/bevy_ecs/src/bundle.rs

@@ -1,6 +1,6 @@
 //! Types for handling [`Bundle`]s.
 //!
-//! This module contains the `Bundle` trait and some other helper types.
+//! This module contains the [`Bundle`] trait and some other helper types.
 
 pub use bevy_ecs_macros::Bundle;
 
@@ -13,7 +13,7 @@ use crate::{
 use bevy_ecs_macros::all_tuples;
 use std::{any::TypeId, collections::HashMap};
 
-/// An ordered collection of components.
+/// An ordered collection of [`Component`]s.
 ///
 /// Commonly used for spawning entities and adding and removing components in bulk. This
 /// trait is automatically implemented for tuples of components: `(ComponentA, ComponentB)`
@@ -71,33 +71,32 @@ use std::{any::TypeId, collections::HashMap};
 ///
 /// # Safety
 ///
-/// - [Bundle::component_ids] must return the ComponentId for each component type in the bundle, in the
-///   _exact_ order that [Bundle::get_components] is called.
-/// - [Bundle::from_components] must call `func` exactly once for each [ComponentId] returned by
-///   [Bundle::component_ids].
+/// - [`Bundle::component_ids`] must return the [`ComponentId`] for each component type in the
+/// bundle, in the _exact_ order that [`Bundle::get_components`] is called.
+/// - [`Bundle::from_components`] must call `func` exactly once for each [`ComponentId`] returned by
+///   [`Bundle::component_ids`].
 pub unsafe trait Bundle: Send + Sync + 'static {
-    /// Gets this [Bundle]'s component ids, in the order of this bundle's Components
+    /// Gets this [`Bundle`]'s component ids, in the order of this bundle's [`Component`]s
     fn component_ids(components: &mut Components, storages: &mut Storages) -> Vec<ComponentId>;
 
     /// Calls `func`, which should return data for each component in the bundle, in the order of
-    /// this bundle's Components
+    /// this bundle's [`Component`]s
     ///
     /// # Safety
     /// Caller must return data for each component in the bundle, in the order of this bundle's
-    /// Components
+    /// [`Component`]s
     unsafe fn from_components(func: impl FnMut() -> *mut u8) -> Self
     where
         Self: Sized;
 
-    /// Calls `func` on each value, in the order of this bundle's Components. This will
-    /// "mem::forget" the bundle fields, so callers are responsible for dropping the fields if
-    /// that is desirable.
+    /// Calls `func` on each value, in the order of this bundle's [`Component`]s. This will
+    /// [`std::mem::forget`] the bundle fields, so callers are responsible for dropping the fields
+    /// if that is desirable.
     fn get_components(self, func: impl FnMut(*mut u8));
 }
 
 macro_rules! tuple_impl {
     ($($name: ident),*) => {
-        /// SAFE: Component is returned in tuple-order. [Bundle::from_components] and [Bundle::get_components] use tuple-order
         unsafe impl<$($name: Component),*> Bundle for ($($name,)*) {
             #[allow(unused_variables)]
             fn component_ids(components: &mut Components, storages: &mut Storages) -> Vec<ComponentId> {
@@ -258,7 +257,8 @@ impl BundleInfo {
     }
 
     /// # Safety
-    /// `table` must be the "new" table for `entity`. `table_row` must have space allocated for the `entity`, `bundle` must match this BundleInfo's type
+    /// `table` must be the "new" table for `entity`. `table_row` must have space allocated for the
+    /// `entity`, `bundle` must match this [`BundleInfo`]'s type
     #[inline]
     #[allow(clippy::too_many_arguments)]
     unsafe fn write_components<T: Bundle>(
@@ -301,9 +301,9 @@ impl BundleInfo {
         });
     }
 
-    /// Adds a bundle to the given archetype and returns the resulting archetype. This could be the same
-    /// [ArchetypeId], in the event that adding the given bundle does not result in an Archetype change.
-    /// Results are cached in the Archetype Graph to avoid redundant work.
+    /// Adds a bundle to the given archetype and returns the resulting archetype. This could be the
+    /// same [`ArchetypeId`], in the event that adding the given bundle does not result in an
+    /// [`Archetype`] change. Results are cached in the [`Archetype`] graph to avoid redundant work.
     pub(crate) fn add_bundle_to_archetype(
         &self,
         archetypes: &mut Archetypes,
@@ -409,8 +409,8 @@ pub(crate) enum InsertBundleResult<'a> {
 
 impl<'a, 'b> BundleInserter<'a, 'b> {
     /// # Safety
-    /// `entity` must currently exist in the source archetype for this inserter. `archetype_index` must be `entity`'s location in the archetype.
-    /// `T` must match this BundleInfo's type
+    /// `entity` must currently exist in the source archetype for this inserter. `archetype_index`
+    /// must be `entity`'s location in the archetype. `T` must match this [`BundleInfo`]'s type
     #[inline]
     pub unsafe fn insert<T: Bundle>(
         &mut self,
@@ -538,7 +538,7 @@ impl<'a, 'b> BundleSpawner<'a, 'b> {
         self.table.reserve(additional);
     }
     /// # Safety
-    /// `entity` must be allocated (but non existent), `T` must match this BundleInfo's type
+    /// `entity` must be allocated (but non-existent), `T` must match this [`BundleInfo`]'s type
     #[inline]
     pub unsafe fn spawn_non_existent<T: Bundle>(
         &mut self,
@@ -562,7 +562,7 @@ impl<'a, 'b> BundleSpawner<'a, 'b> {
     }
 
     /// # Safety
-    /// `T` must match this BundleInfo's type
+    /// `T` must match this [`BundleInfo`]'s type
     #[inline]
     pub unsafe fn spawn<T: Bundle>(&mut self, bundle: T) -> Entity {
         let entity = self.entities.alloc();
@@ -612,7 +612,7 @@ impl Bundles {
 
 /// # Safety
 ///
-/// `component_id` must be valid [ComponentId]'s
+/// `component_id` must be valid [`ComponentId`]'s
 unsafe fn initialize_bundle(
     bundle_type_name: &'static str,
     component_ids: Vec<ComponentId>,

crates/bevy_ecs/src/component.rs

@@ -289,7 +289,7 @@ impl Components {
 
     /// # Safety
     ///
-    /// `id` must be a valid [ComponentId]
+    /// `id` must be a valid [`ComponentId`]
     #[inline]
     pub unsafe fn get_info_unchecked(&self, id: ComponentId) -> &ComponentInfo {
         debug_assert!(id.index() < self.components.len());

crates/bevy_ecs/src/entity/mod.rs

@@ -493,9 +493,9 @@ impl Entities {
     /// `reserve_entities`, then initializes each one using the supplied function.
     ///
     /// # Safety
-    /// Flush _must_ set the entity location to the correct ArchetypeId for the given Entity
-    /// each time init is called. This _can_ be ArchetypeId::INVALID, provided the Entity has
-    /// not been assigned to an Archetype.
+    /// Flush _must_ set the entity location to the correct [`ArchetypeId`] for the given [`Entity`]
+    /// each time init is called. This _can_ be [`ArchetypeId::INVALID`], provided the [`Entity`]
+    /// has not been assigned to an [`Archetype`][crate::archetype::Archetype].
     pub unsafe fn flush(&mut self, mut init: impl FnMut(Entity, &mut EntityLocation)) {
         let free_cursor = self.free_cursor.get_mut();
         let current_free_cursor = *free_cursor;

crates/bevy_ecs/src/event.rs

@@ -67,7 +67,7 @@ enum State {
 /// [`Events::update`] exactly once per update/frame.
 ///
 /// [`Events::update_system`] is a system that does this, typically intialized automatically using
-/// [`App::add_event`]. [EventReader]s are expected to read events from this collection at
+/// [`App::add_event`]. [`EventReader`]s are expected to read events from this collection at
 /// least once per loop/frame.
 /// Events will persist across a single frame boundary and so ordering of event producers and
 /// consumers is not critical (although poorly-planned ordering may cause accumulating lag).
@@ -103,16 +103,16 @@ enum State {
 ///
 /// # Details
 ///
-/// [Events] is implemented using a double buffer. Each call to [Events::update] swaps buffers and
-/// clears out the oldest buffer. [EventReader]s that read at least once per update will never drop
-/// events. [EventReader]s that read once within two updates might still receive some events.
-/// [EventReader]s that read after two updates are guaranteed to drop all events that occurred
+/// [`Events`] is implemented using a double buffer. Each call to [`Events::update`] swaps buffers
+/// and clears out the oldest buffer. [`EventReader`]s that read at least once per update will never
+/// drop events. [`EventReader`]s that read once within two updates might still receive some events.
+/// [`EventReader`]s that read after two updates are guaranteed to drop all events that occurred
 /// before those updates.
 ///
-/// The buffers in [Events] will grow indefinitely if [Events::update] is never called.
+/// The buffers in [`Events`] will grow indefinitely if [`Events::update`] is never called.
 ///
-/// An alternative call pattern would be to call [Events::update] manually across frames to control
-/// when events are cleared.
+/// An alternative call pattern would be to call [`Events::update`] manually across frames to
+/// control when events are cleared.
 /// This complicates consumption and risks ever-expanding memory usage if not cleaned up,
 /// but can be done by adding your event as a resource instead of using [`App::add_event`].
 ///
@@ -254,9 +254,9 @@ fn internal_event_reader<'a, T>(
 }
 
 impl<'w, 's, T: Resource> EventReader<'w, 's, T> {
-    /// Iterates over the events this EventReader has not seen yet. This updates the EventReader's
-    /// event counter, which means subsequent event reads will not include events that happened
-    /// before now.
+    /// Iterates over the events this [`EventReader`] has not seen yet. This updates the
+    /// [`EventReader`]'s event counter, which means subsequent event reads will not include events
+    /// that happened before now.
     pub fn iter(&mut self) -> impl DoubleEndedIterator<Item = &T> {
         self.iter_with_id().map(|(event, _id)| event)
     }
@@ -271,7 +271,7 @@ impl<'w, 's, T: Resource> EventReader<'w, 's, T> {
 }
 
 impl<T: Resource> Events<T> {
-    /// "Sends" an `event` by writing it to the current event buffer. [EventReader]s can then read
+    /// "Sends" an `event` by writing it to the current event buffer. [`EventReader`]s can then read
     /// the event.
     pub fn send(&mut self, event: T) {
         let event_id = EventId {
@@ -290,16 +290,16 @@ impl<T: Resource> Events<T> {
         self.event_count += 1;
     }
 
-    /// Gets a new [ManualEventReader]. This will include all events already in the event buffers.
+    /// Gets a new [`ManualEventReader`]. This will include all events already in the event buffers.
     pub fn get_reader(&self) -> ManualEventReader<T> {
         ManualEventReader {
             last_event_count: 0,
             _marker: PhantomData,
         }
     }
 
-    /// Gets a new [ManualEventReader]. This will ignore all events already in the event buffers. It
-    /// will read all future events.
+    /// Gets a new [`ManualEventReader`]. This will ignore all events already in the event buffers.
+    /// It will read all future events.
     pub fn get_reader_current(&self) -> ManualEventReader<T> {
         ManualEventReader {
             last_event_count: self.event_count,
@@ -324,7 +324,7 @@ impl<T: Resource> Events<T> {
         }
     }
 
-    /// A system that calls [Events::update] once per frame.
+    /// A system that calls [`Events::update`] once per frame.
     pub fn update_system(mut events: ResMut<Self>) {
         events.update();
     }

crates/bevy_ecs/src/query/fetch.rs

@@ -21,13 +21,13 @@ use std::{
 ///
 /// See [`Query`](crate::system::Query) for a primer on queries.
 ///
-/// # Basic WorldQueries
+/// # Basic [`WorldQuery`]'s
 ///
 /// Here is a small list of the most important world queries to know about where `C` stands for a
 /// [`Component`] and `WQ` stands for a [`WorldQuery`]:
 /// - `&C`: Queries immutably for the component `C`
 /// - `&mut C`: Queries mutably for the component `C`
-/// - `Option<WQ>`: Queries the inner WorldQuery `WQ` but instead of discarding the entity if the world
+/// - `Option<WQ>`: Queries the inner [`WorldQuery`] `WQ` but instead of discarding the entity if the world
 ///     query fails it returns [`None`]. See [`Query`](crate::system::Query).
 /// - `(WQ1, WQ2, ...)`: Queries all contained world queries allowing to query for more than one thing.
 ///     This is the `And` operator for filters. See [`Or`].
@@ -57,8 +57,8 @@ pub trait Fetch<'world, 'state>: Sized {
     ///
     /// # Safety
     ///
-    /// `state` must have been initialized (via [FetchState::init]) using the same `world` passed in
-    /// to this function.
+    /// `state` must have been initialized (via [`FetchState::init`]) using the same `world` passed
+    /// in to this function.
     unsafe fn init(
         world: &World,
         state: &Self::State,
@@ -78,8 +78,8 @@ pub trait Fetch<'world, 'state>: Sized {
     ///
     /// # Safety
     ///
-    /// `archetype` and `tables` must be from the [`World`] [`Fetch::init`] was called on. `state` must
-    /// be the [Self::State] this was initialized with.
+    /// `archetype` and `tables` must be from the [`World`] [`Fetch::init`] was called on. `state`
+    /// must be the [`Self::State`] this was initialized with.
     unsafe fn set_archetype(&mut self, state: &Self::State, archetype: &Archetype, tables: &Tables);
 
     /// Adjusts internal state to account for the next [`Table`]. This will always be called on tables
@@ -88,7 +88,7 @@ pub trait Fetch<'world, 'state>: Sized {
     /// # Safety
     ///
     /// `table` must be from the [`World`] [`Fetch::init`] was called on. `state` must be the
-    /// [Self::State] this was initialized with.
+    /// [`Self::State`] this was initialized with.
     unsafe fn set_table(&mut self, state: &Self::State, table: &Table);
 
     /// Fetch [`Self::Item`] for the given `archetype_index` in the current [`Archetype`]. This must
@@ -677,7 +677,7 @@ pub struct OptionFetch<T> {
     matches: bool,
 }
 
-/// SAFETY: OptionFetch is read only because T is read only
+/// SAFETY: [`OptionFetch`] is read only because `T` is read only
 unsafe impl<T: ReadOnlyFetch> ReadOnlyFetch for OptionFetch<T> {}
 
 /// The [`FetchState`] of `Option<T>`.

crates/bevy_ecs/src/query/iter.rs

@@ -35,7 +35,7 @@ where
     /// This does not check for mutable query correctness. To be safe, make sure mutable queries
     /// have unique access to the components they query.
     /// This does not validate that `world.id()` matches `query_state.world_id`. Calling this on a `world`
-    /// with a mismatched WorldId is unsound.
+    /// with a mismatched [`WorldId`] is unsound.
     pub(crate) unsafe fn new(
         world: &'w World,
         query_state: &'s QueryState<Q, F>,
@@ -174,8 +174,8 @@ where
     /// # Safety
     /// This does not check for mutable query correctness. To be safe, make sure mutable queries
     /// have unique access to the components they query.
-    /// This does not validate that `world.id()` matches `query_state.world_id`. Calling this on a `world`
-    /// with a mismatched WorldId is unsound.
+    /// This does not validate that `world.id()` matches `query_state.world_id`. Calling this on a
+    /// `world` with a mismatched [`WorldId`] is unsound.
     pub(crate) unsafe fn new(
         world: &'w World,
         query_state: &'s QueryState<Q, F>,

crates/bevy_ecs/src/query/state.rs

@@ -391,7 +391,7 @@ where
     /// This does not check for mutable query correctness. To be safe, make sure mutable queries
     /// have unique access to the components they query.
     /// This does not validate that `world.id()` matches `self.world_id`. Calling this on a `world`
-    /// with a mismatched WorldId is unsound.
+    /// with a mismatched [`WorldId`] is unsound.
     #[inline]
     pub(crate) unsafe fn iter_unchecked_manual<'w, 's, QF: Fetch<'w, 's, State = Q::State>>(
         &'s self,
@@ -411,7 +411,7 @@ where
     /// This does not check for mutable query correctness. To be safe, make sure mutable queries
     /// have unique access to the components they query.
     /// This does not validate that `world.id()` matches `self.world_id`. Calling this on a `world`
-    /// with a mismatched WorldId is unsound.
+    /// with a mismatched [`WorldId`] is unsound.
     #[inline]
     pub(crate) unsafe fn iter_combinations_unchecked_manual<
         'w,
@@ -450,7 +450,7 @@ where
     }
 
     /// Runs `func` on each query result for the given [`World`]. This is faster than the equivalent
-    /// iter_mut() method, but cannot be chained like a normal [`Iterator`].
+    /// `iter_mut()` method, but cannot be chained like a normal [`Iterator`].
     #[inline]
     pub fn for_each_mut<'w, 's, FN: FnMut(<Q::Fetch as Fetch<'w, 's>>::Item)>(
         &'s mut self,
@@ -590,7 +590,7 @@ where
     /// This does not check for mutable query correctness. To be safe, make sure mutable queries
     /// have unique access to the components they query.
     /// This does not validate that `world.id()` matches `self.world_id`. Calling this on a `world`
-    /// with a mismatched WorldId is unsound.
+    /// with a mismatched [`WorldId`] is unsound.
     pub(crate) unsafe fn for_each_unchecked_manual<
         'w,
         's,
@@ -650,7 +650,7 @@ where
     /// This does not check for mutable query correctness. To be safe, make sure mutable queries
     /// have unique access to the components they query.
     /// This does not validate that `world.id()` matches `self.world_id`. Calling this on a `world`
-    /// with a mismatched WorldId is unsound.
+    /// with a mismatched [`WorldId`] is unsound.
     pub(crate) unsafe fn par_for_each_unchecked_manual<
         'w,
         's,

crates/bevy_ecs/src/schedule/executor.rs

@@ -41,8 +41,8 @@ impl ParallelSystemExecutor for SingleThreadedExecutor {
 }
 
 impl SingleThreadedExecutor {
-    /// Calls system.new_archetype() for each archetype added since the last call to
-    /// [update_archetypes] and updates cached archetype_component_access.
+    /// Calls `system.new_archetype()` for each archetype added since the last call to
+    /// `update_archetypes` and updates cached `archetype_component_access`.
     fn update_archetypes(&mut self, systems: &mut [ParallelSystemContainer], world: &World) {
         let archetypes = world.archetypes();
         let new_generation = archetypes.generation();

crates/bevy_ecs/src/schedule/executor_parallel.rs

@@ -154,8 +154,8 @@ impl ParallelSystemExecutor for ParallelExecutor {
 }
 
 impl ParallelExecutor {
-    /// Calls system.new_archetype() for each archetype added since the last call to
-    /// [update_archetypes] and updates cached archetype_component_access.
+    /// Calls `system.new_archetype()` for each archetype added since the last call to
+    /// `update_archetypes` and updates cached `archetype_component_access`.
     fn update_archetypes(&mut self, systems: &mut [ParallelSystemContainer], world: &World) {
         #[cfg(feature = "trace")]
         let span = bevy_utils::tracing::info_span!("update_archetypes");