From 313875507d4a4378452222f96aba3f2b3e14e749 Mon Sep 17 00:00:00 2001
From: mo <mostlychai@proton.me>
Date: Mon, 15 Jun 2026 12:30:56 +0100
Subject: [PATCH 1/2] fix documentation for get_components method family for
 result return types

---
 crates/bevy_ecs/src/world/entity_access/entity_mut.rs | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/crates/bevy_ecs/src/world/entity_access/entity_mut.rs b/crates/bevy_ecs/src/world/entity_access/entity_mut.rs
index d28fe6b5fee94..1eba12be92b89 100644
--- a/crates/bevy_ecs/src/world/entity_access/entity_mut.rs
+++ b/crates/bevy_ecs/src/world/entity_access/entity_mut.rs
@@ -176,7 +176,7 @@ impl<'w> EntityMut<'w> {
     }
 
     /// Returns read-only components for the current entity that match the query `Q`,
-    /// or `None` if the entity does not have the components required by the query `Q`.
+    /// or [`QueryAccessError`] if the entity does not have the components required by the query `Q`.
     pub fn get_components<Q: ReadOnlyQueryData + ReleaseStateQueryData + SingleEntityQueryData>(
         &self,
     ) -> Result<Q::Item<'_, 'static>, QueryAccessError> {
@@ -184,7 +184,7 @@ impl<'w> EntityMut<'w> {
     }
 
     /// Returns components for the current entity that match the query `Q`,
-    /// or `None` if the entity does not have the components required by the query `Q`.
+    /// or [`QueryAccessError`] if the entity does not have the components required by the query `Q`.
     ///
     /// # Example
     ///
@@ -252,7 +252,7 @@ impl<'w> EntityMut<'w> {
     }
 
     /// Consumes self and returns components for the current entity that match the query `Q` for the world lifetime `'w`,
-    /// or `None` if the entity does not have the components required by the query `Q`.
+    /// or [`QueryAccessError`] if the entity does not have the components required by the query `Q`.
     ///
     /// # Example
     ///
@@ -295,7 +295,7 @@ impl<'w> EntityMut<'w> {
     }
 
     /// Consumes self and returns components for the current entity that match the query `Q` for the world lifetime `'w`,
-    /// or `None` if the entity does not have the components required by the query `Q`.
+    /// or [`QueryAccessError`] if the entity does not have the components required by the query `Q`.
     ///
     /// The checks for aliasing mutable references may be expensive.
     /// If performance is a concern, consider making multiple calls to [`Self::get_mut`].

From a1d9aedcc8db3e6265cd3346b4f40fbeae57e309 Mon Sep 17 00:00:00 2001
From: mo <mostlychai@proton.me>
Date: Mon, 15 Jun 2026 12:45:19 +0100
Subject: [PATCH 2/2] moved safety blocks above example for
 into/get_components_mut_unchecked

---
 .../src/world/entity_access/entity_mut.rs        | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/crates/bevy_ecs/src/world/entity_access/entity_mut.rs b/crates/bevy_ecs/src/world/entity_access/entity_mut.rs
index 1eba12be92b89..7d8dcf87a3dfd 100644
--- a/crates/bevy_ecs/src/world/entity_access/entity_mut.rs
+++ b/crates/bevy_ecs/src/world/entity_access/entity_mut.rs
@@ -186,6 +186,10 @@ impl<'w> EntityMut<'w> {
     /// Returns components for the current entity that match the query `Q`,
     /// or [`QueryAccessError`] if the entity does not have the components required by the query `Q`.
     ///
+    /// # Safety
+    /// It is the caller's responsibility to ensure that
+    /// the `QueryData` does not provide aliasing mutable references to the same component.
+    ///
     /// # Example
     ///
     /// ```
@@ -208,10 +212,6 @@ impl<'w> EntityMut<'w> {
     /// // entity.get_components_mut_unchecked::<(&mut X, &mut X)>();
     /// ```
     ///
-    /// # Safety
-    /// It is the caller's responsibility to ensure that
-    /// the `QueryData` does not provide aliasing mutable references to the same component.
-    ///
     /// # See also
     ///
     /// - [`Self::get_components_mut`] for the safe version that performs aliasing checks
@@ -254,6 +254,10 @@ impl<'w> EntityMut<'w> {
     /// Consumes self and returns components for the current entity that match the query `Q` for the world lifetime `'w`,
     /// or [`QueryAccessError`] if the entity does not have the components required by the query `Q`.
     ///
+    /// # Safety
+    /// It is the caller's responsibility to ensure that
+    /// the `QueryData` does not provide aliasing mutable references to the same component.
+    ///
     /// # Example
     ///
     /// ```
@@ -276,10 +280,6 @@ impl<'w> EntityMut<'w> {
     /// // entity.into_components_mut_unchecked::<(&mut X, &mut X)>();
     /// ```
     ///
-    /// # Safety
-    /// It is the caller's responsibility to ensure that
-    /// the `QueryData` does not provide aliasing mutable references to the same component.
-    ///
     /// # See also
     ///
     /// - [`Self::into_components_mut`] for the safe version that performs aliasing checks