From cc2716c235ed02f4e0cb30385e63adf46b41e965 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kristoffer=20S=C3=B8holm?= Date: Sun, 18 Feb 2024 22:58:26 +0100 Subject: [PATCH] Update documentation for WorldQuery and filters (#11952) # Objective `update_archetype_component_access` was removed from queries in #9774, but some documentation still refers to it. ## Solution Update the documentation. Since a bunch of these were in SAFETY comments it would be nice if someone who knows the details better could check that the rest of those comments are still valid. --- crates/bevy_ecs/src/query/filter.rs | 12 +++++------- crates/bevy_ecs/src/query/world_query.rs | 6 +++--- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/crates/bevy_ecs/src/query/filter.rs b/crates/bevy_ecs/src/query/filter.rs index a8d225ab81173f..0216ad5a43df9e 100644 --- a/crates/bevy_ecs/src/query/filter.rs +++ b/crates/bevy_ecs/src/query/filter.rs @@ -70,8 +70,6 @@ use std::{cell::UnsafeCell, marker::PhantomData}; /// [`matches_component_set`]: Self::matches_component_set /// [`Query`]: crate::system::Query /// [`State`]: Self::State -/// [`update_archetype_component_access`]: Self::update_archetype_component_access -/// [`update_component_access`]: Self::update_component_access pub trait QueryFilter: WorldQuery { /// Returns true if (and only if) this Filter relies strictly on archetypes to limit which @@ -123,7 +121,7 @@ pub trait QueryFilter: WorldQuery { pub struct With(PhantomData); /// SAFETY: -/// `update_component_access` and `update_archetype_component_access` do not add any accesses. +/// `update_component_access` does not add any accesses. /// This is sound because `fetch` does not access any components. /// `update_component_access` adds a `With` filter for `T`. /// This is sound because `matches_component_set` returns whether the set contains the component. @@ -231,7 +229,7 @@ impl QueryFilter for With { pub struct Without(PhantomData); /// SAFETY: -/// `update_component_access` and `update_archetype_component_access` do not add any accesses. +/// `update_component_access` does not add any accesses. /// This is sound because `fetch` does not access any components. /// `update_component_access` adds a `Without` filter for `T`. /// This is sound because `matches_component_set` returns whether the set does not contain the component. @@ -366,7 +364,7 @@ macro_rules! impl_query_filter_tuple { #[allow(clippy::unused_unit)] /// SAFETY: /// `fetch` accesses are a subset of the subqueries' accesses - /// This is sound because `update_component_access` and `update_archetype_component_access` adds accesses according to the implementations of all the subqueries. + /// This is sound because `update_component_access` adds accesses according to the implementations of all the subqueries. /// `update_component_access` replace the filters with a disjunction where every element is a conjunction of the previous filters and the filters of one of the subqueries. /// This is sound because `matches_component_set` returns a disjunction of the results of the subqueries' implementations. unsafe impl<$($filter: QueryFilter),*> WorldQuery for Or<($($filter,)*)> { @@ -579,7 +577,7 @@ pub struct AddedFetch<'w> { /// SAFETY: /// `fetch` accesses a single component in a readonly way. -/// This is sound because `update_component_access` and `update_archetype_component_access` add read access for that component and panic when appropriate. +/// This is sound because `update_component_access` adds read access for that component and panics when appropriate. /// `update_component_access` adds a `With` filter for a component. /// This is sound because `matches_component_set` returns whether the set contains that component. unsafe impl WorldQuery for Added { @@ -779,7 +777,7 @@ pub struct ChangedFetch<'w> { /// SAFETY: /// `fetch` accesses a single component in a readonly way. -/// This is sound because `update_component_access` and `update_archetype_component_access` add read access for that component and panic when appropriate. +/// This is sound because `update_component_access` add read access for that component and panics when appropriate. /// `update_component_access` adds a `With` filter for a component. /// This is sound because `matches_component_set` returns whether the set contains that component. unsafe impl WorldQuery for Changed { diff --git a/crates/bevy_ecs/src/query/world_query.rs b/crates/bevy_ecs/src/query/world_query.rs index ad09c5fe447bf4..18d52abc8cca95 100644 --- a/crates/bevy_ecs/src/query/world_query.rs +++ b/crates/bevy_ecs/src/query/world_query.rs @@ -57,7 +57,6 @@ pub unsafe trait WorldQuery { /// /// # Safety /// - /// - `world` must have permission to access any of the components specified in `Self::update_archetype_component_access`. /// - `state` must have been initialized (via [`WorldQuery::init_state`]) using the same `world` passed /// in to this function. unsafe fn init_fetch<'w>( @@ -128,7 +127,8 @@ pub unsafe trait WorldQuery { /// Creates and initializes a [`State`](WorldQuery::State) for this [`WorldQuery`] type. fn init_state(world: &mut World) -> Self::State; - /// Attempts to initializes a [`State`](WorldQuery::State) for this [`WorldQuery`] type. + /// Attempts to initialize a [`State`](WorldQuery::State) for this [`WorldQuery`] type using read-only + /// access to the [`World`]. fn get_state(world: &World) -> Option; /// Returns `true` if this query matches a set of components. Otherwise, returns `false`. @@ -145,7 +145,7 @@ macro_rules! impl_tuple_world_query { #[allow(clippy::unused_unit)] /// SAFETY: /// `fetch` accesses are the conjunction of the subqueries' accesses - /// This is sound because `update_component_access` and `update_archetype_component_access` adds accesses according to the implementations of all the subqueries. + /// This is sound because `update_component_access` adds accesses according to the implementations of all the subqueries. /// `update_component_access` adds all `With` and `Without` filters from the subqueries. /// This is sound because `matches_component_set` always returns `false` if any the subqueries' implementations return `false`. unsafe impl<$($name: WorldQuery),*> WorldQuery for ($($name,)*) {