Update docs and safety invariants

Author: BoxyUwU

crates/bevy_ecs/macros/src/fetch.rs

@@ -267,8 +267,7 @@ pub fn derive_world_query_impl(ast: DeriveInput) -> TokenStream {
             #(#ignored_field_idents: #ignored_field_types,)*
         }
 
-        // SAFETY: `update_component_access` and `update_archetype_component_access` are called for each item in the struct
-        unsafe impl #user_impl_generics #path::query::FetchState for #state_struct_name #user_ty_generics #user_where_clauses {
+        impl #user_impl_generics #path::query::FetchState for #state_struct_name #user_ty_generics #user_where_clauses {
             fn init(world: &mut #path::world::World) -> Self {
                 #state_struct_name {
                     #(#field_idents: <<#field_types as #path::query::WorldQuery>::State as #path::query::FetchState>::init(world),)*
@@ -304,7 +303,8 @@ pub fn derive_world_query_impl(ast: DeriveInput) -> TokenStream {
                 #(#(#ignored_field_attrs)* #ignored_field_visibilities #ignored_field_idents: #ignored_field_types,)*
             }
 
-            impl #user_impl_generics #path::query::WorldQuery for #read_only_struct_name #user_ty_generics #user_where_clauses {
+            // SAFETY: `update_component_access` and `update_archetype_component_access` are called on every field
+            unsafe impl #user_impl_generics #path::query::WorldQuery for #read_only_struct_name #user_ty_generics #user_where_clauses {
                 type ReadOnly = Self;
                 type State = #state_struct_name #user_ty_generics;
 
@@ -372,7 +372,8 @@ pub fn derive_world_query_impl(ast: DeriveInput) -> TokenStream {
 
         #read_only_world_query_impl
 
-        impl #user_impl_generics #path::query::WorldQuery for #struct_name #user_ty_generics #user_where_clauses {
+        // SAFETY: `update_component_access` and `update_archetype_component_access` are called on every field
+        unsafe impl #user_impl_generics #path::query::WorldQuery for #struct_name #user_ty_generics #user_where_clauses {
             type ReadOnly = #read_only_struct_name #user_ty_generics;
             type State = #state_struct_name #user_ty_generics;
             fn shrink<'__wlong: '__wshort, '__wshort>(item: #path::query::#item_type_alias<'__wlong, Self>)

crates/bevy_ecs/src/query/fetch.rs

@@ -292,7 +292,13 @@ use std::{cell::UnsafeCell, marker::PhantomData};
 ///
 /// # bevy_ecs::system::assert_is_system(my_system);
 /// ```
-pub trait WorldQuery: for<'w> WorldQueryGats<'w, _State = Self::State> {
+/// # Safety
+///
+/// Implementor must ensure that [`WorldQuery::update_component_access`] and
+/// [`WorldQuery::update_archetype_component_access`] exactly reflects the results of
+/// [`FetchState::matches_archetype`], [`FetchState::matches_table`], [`Fetch::archetype_fetch`], and
+/// [`Fetch::table_fetch`].
+pub unsafe trait WorldQuery: for<'w> WorldQueryGats<'w, _State = Self::State> {
     type ReadOnly: ReadOnlyWorldQuery<State = Self::State>;
     type State: FetchState;
 
@@ -429,20 +435,14 @@ pub trait Fetch<'world>: Sized {
 /// State used to construct a Fetch. This will be cached inside [`QueryState`](crate::query::QueryState),
 ///  so it is best to move as much data / computation here as possible to reduce the cost of
 /// constructing Fetch.
-///
-/// # Safety
-///
-/// Implementor must ensure that [`FetchState::update_component_access`] and
-/// [`FetchState::update_archetype_component_access`] exactly reflects the results of
-/// [`FetchState::matches_archetype`], [`FetchState::matches_table`], [`Fetch::archetype_fetch`], and
-/// [`Fetch::table_fetch`].
-pub unsafe trait FetchState: Send + Sync + Sized {
+pub trait FetchState: Send + Sync + Sized {
     fn init(world: &mut World) -> Self;
     fn matches_archetype(&self, archetype: &Archetype) -> bool;
     fn matches_table(&self, table: &Table) -> bool;
 }
 
-impl WorldQuery for Entity {
+/// SAFETY: no component or archetype access
+unsafe impl WorldQuery for Entity {
     type ReadOnly = Self;
     type State = EntityState;
 
@@ -474,8 +474,7 @@ unsafe impl ReadOnlyWorldQuery for Entity {}
 #[doc(hidden)]
 pub struct EntityState;
 
-// SAFETY: no component or archetype access
-unsafe impl FetchState for EntityState {
+impl FetchState for EntityState {
     fn init(_world: &mut World) -> Self {
         Self
     }
@@ -541,7 +540,9 @@ impl<'w> Fetch<'w> for EntityFetch<'w> {
     }
 }
 
-impl<T: Component> WorldQuery for &T {
+// SAFETY: component access and archetype component access are properly updated to reflect that T is
+// read
+unsafe impl<T: Component> WorldQuery for &T {
     type ReadOnly = Self;
     type State = ReadState<T>;
 
@@ -578,9 +579,7 @@ pub struct ReadState<T> {
     marker: PhantomData<T>,
 }
 
-// SAFETY: component access and archetype component access are properly updated to reflect that T is
-// read
-unsafe impl<T: Component> FetchState for ReadState<T> {
+impl<T: Component> FetchState for ReadState<T> {
     fn init(world: &mut World) -> Self {
         let component_id = world.init_component::<T>();
         ReadState {
@@ -725,7 +724,9 @@ impl<'w, T: Component> Fetch<'w> for ReadFetch<'w, T> {
     }
 }
 
-impl<'w, T: Component> WorldQuery for &'w mut T {
+/// SAFETY: component access and archetype component access are properly updated to reflect that T is
+/// read and write
+unsafe impl<'w, T: Component> WorldQuery for &'w mut T {
     type ReadOnly = &'w T;
     type State = ReadState<T>;
 
@@ -908,7 +909,9 @@ impl<'w, 's, T: Component> Fetch<'w> for WriteFetch<'w, T> {
     }
 }
 
-impl<T: WorldQuery> WorldQuery for Option<T> {
+// SAFETY: component access and archetype component access are properly updated according to the
+// internal Fetch
+unsafe impl<T: WorldQuery> WorldQuery for Option<T> {
     type ReadOnly = Option<T::ReadOnly>;
     type State = OptionState<T::State>;
 
@@ -948,9 +951,7 @@ pub struct OptionState<T: FetchState> {
     state: T,
 }
 
-// SAFETY: component access and archetype component access are properly updated according to the
-// internal Fetch
-unsafe impl<T: FetchState> FetchState for OptionState<T> {
+impl<T: FetchState> FetchState for OptionState<T> {
     fn init(world: &mut World) -> Self {
         Self {
             state: T::init(world),
@@ -1095,7 +1096,9 @@ impl<T: Component> ChangeTrackers<T> {
     }
 }
 
-impl<T: Component> WorldQuery for ChangeTrackers<T> {
+// SAFETY: component access and archetype component access are properly updated to reflect that T is
+// read
+unsafe impl<T: Component> WorldQuery for ChangeTrackers<T> {
     type ReadOnly = Self;
     type State = ChangeTrackersState<T>;
 
@@ -1132,9 +1135,7 @@ pub struct ChangeTrackersState<T> {
     marker: PhantomData<T>,
 }
 
-// SAFETY: component access and archetype component access are properly updated to reflect that T is
-// read
-unsafe impl<T: Component> FetchState for ChangeTrackersState<T> {
+impl<T: Component> FetchState for ChangeTrackersState<T> {
     fn init(world: &mut World) -> Self {
         let component_id = world.init_component::<T>();
         Self {
@@ -1377,10 +1378,9 @@ macro_rules! impl_tuple_fetch {
             }
         }
 
-        // SAFETY: update_component_access and update_archetype_component_access are called for each item in the tuple
         #[allow(non_snake_case)]
         #[allow(clippy::unused_unit)]
-        unsafe impl<$($name: FetchState),*> FetchState for ($($name,)*) {
+        impl<$($name: FetchState),*> FetchState for ($($name,)*) {
             fn init(_world: &mut World) -> Self {
                 ($($name::init(_world),)*)
             }
@@ -1398,7 +1398,8 @@ macro_rules! impl_tuple_fetch {
 
         #[allow(non_snake_case)]
         #[allow(clippy::unused_unit)]
-        impl<$($name: WorldQuery),*> WorldQuery for ($($name,)*) {
+        // SAFETY: update_component_access and update_archetype_component_access are called for each item in the tuple
+        unsafe impl<$($name: WorldQuery),*> WorldQuery for ($($name,)*) {
             type ReadOnly = ($($name::ReadOnly,)*);
             type State = ($($name::State,)*);
 
@@ -1500,10 +1501,9 @@ macro_rules! impl_anytuple_fetch {
             }
         }
 
-        // SAFETY: update_component_access and update_archetype_component_access are called for each item in the tuple
         #[allow(non_snake_case)]
         #[allow(clippy::unused_unit)]
-        unsafe impl<$($name: FetchState),*> FetchState for AnyOf<($($name,)*)> {
+        impl<$($name: FetchState),*> FetchState for AnyOf<($($name,)*)> {
             fn init(_world: &mut World) -> Self {
                 AnyOf(($($name::init(_world),)*))
             }
@@ -1521,7 +1521,8 @@ macro_rules! impl_anytuple_fetch {
 
         #[allow(non_snake_case)]
         #[allow(clippy::unused_unit)]
-        impl<$($name: WorldQuery),*> WorldQuery for AnyOf<($($name,)*)> {
+        // SAFETY: update_component_access and update_archetype_component_access are called for each item in the tuple
+        unsafe impl<$($name: WorldQuery),*> WorldQuery for AnyOf<($($name,)*)> {
             type ReadOnly = AnyOf<($($name::ReadOnly,)*)>;
             type State = AnyOf<($($name::State,)*)>;
 

crates/bevy_ecs/src/query/filter.rs

@@ -44,7 +44,8 @@ use super::ReadOnlyWorldQuery;
 /// ```
 pub struct With<T>(PhantomData<T>);
 
-impl<T: Component> WorldQuery for With<T> {
+// SAFETY: no component access or archetype component access
+unsafe impl<T: Component> WorldQuery for With<T> {
     type ReadOnly = Self;
     type State = WithState<T>;
 
@@ -81,8 +82,7 @@ pub struct WithState<T> {
     marker: PhantomData<T>,
 }
 
-// SAFETY: no component access or archetype component access
-unsafe impl<T: Component> FetchState for WithState<T> {
+impl<T: Component> FetchState for WithState<T> {
     fn init(world: &mut World) -> Self {
         let component_id = world.init_component::<T>();
         Self {
@@ -187,7 +187,8 @@ impl<T> Copy for WithFetch<T> {}
 /// ```
 pub struct Without<T>(PhantomData<T>);
 
-impl<T: Component> WorldQuery for Without<T> {
+// SAFETY: no component access or archetype component access
+unsafe impl<T: Component> WorldQuery for Without<T> {
     type ReadOnly = Self;
     type State = WithoutState<T>;
 
@@ -224,8 +225,7 @@ pub struct WithoutState<T> {
     marker: PhantomData<T>,
 }
 
-// SAFETY: no component access or archetype component access
-unsafe impl<T: Component> FetchState for WithoutState<T> {
+impl<T: Component> FetchState for WithoutState<T> {
     fn init(world: &mut World) -> Self {
         let component_id = world.init_component::<T>();
         Self {
@@ -350,7 +350,8 @@ macro_rules! impl_query_filter_tuple {
     ($(($filter: ident, $state: ident)),*) => {
         #[allow(unused_variables)]
         #[allow(non_snake_case)]
-        impl<$($filter: WorldQuery),*> WorldQuery for Or<($($filter,)*)> {
+        // SAFETY: update_component_access and update_archetype_component_access are called for each item in the tuple
+        unsafe impl<$($filter: WorldQuery),*> WorldQuery for Or<($($filter,)*)> {
             type ReadOnly = Or<($($filter::ReadOnly,)*)>;
             type State = Or<($($filter::State,)*)>;
 
@@ -442,10 +443,9 @@ macro_rules! impl_query_filter_tuple {
             }
         }
 
-        // SAFETY: update_component_access and update_archetype_component_access are called for each item in the tuple
         #[allow(unused_variables)]
         #[allow(non_snake_case)]
-        unsafe impl<$($filter: FetchState),*> FetchState for Or<($($filter,)*)> {
+        impl<$($filter: FetchState),*> FetchState for Or<($($filter,)*)> {
             fn init(world: &mut World) -> Self {
                 Or(($($filter::init(world),)*))
             }
@@ -500,7 +500,8 @@ macro_rules! impl_tick_filter {
             marker: PhantomData<T>,
         }
 
-        impl<T: Component> WorldQuery for $name<T> {
+        // SAFETY: this reads the T component. archetype component access and component access are updated to reflect that
+        unsafe impl<T: Component> WorldQuery for $name<T> {
             type ReadOnly = Self;
             type State = $state_name<T>;
 
@@ -529,8 +530,7 @@ macro_rules! impl_tick_filter {
             }
         }
 
-        // SAFETY: this reads the T component. archetype component access and component access are updated to reflect that
-        unsafe impl<T: Component> FetchState for $state_name<T> {
+        impl<T: Component> FetchState for $state_name<T> {
             fn init(world: &mut World) -> Self {
                 Self {
                     component_id: world.init_component::<T>(),