First CI pass

crates/bevy_ecs/src/lib.rs

@@ -54,7 +54,9 @@ pub mod prelude {
             ParamSet, Query, ReadOnlySystem, Res, ResMut, Resource, System, SystemParamFunction,
             TermQuery,
         },
-        term_query::TermQueryState,
+        term_query::{
+            FetchedTerm, QueryBuilder, QueryTerm, QueryTermGroup, Term, TermAccess, TermQueryState,
+        },
         world::{EntityMut, EntityRef, EntityWorldMut, FromWorld, World},
     };
 }

crates/bevy_ecs/src/system/function_system.rs

@@ -359,10 +359,10 @@ impl<Marker, F> FunctionSystem<Marker, F>
 where
     F: SystemParamFunction<Marker>,
 {
-    /// Retrieves this systems [SystemParam::State] mutably
+    /// Retrieves this systems [`SystemParam::State`] mutably
     ///
     /// # Safety
-    /// Mutable reference must not be used to put the [SystemParam::State]
+    /// Mutable reference must not be used to put the [`SystemParam::State`]
     /// in an invalid state for this [`FunctionSystem`]
     pub unsafe fn state_mut(&mut self) -> &mut <F::Param as SystemParam>::State {
         // Archetype generation reset so that new params will be updated with all archetypes

crates/bevy_ecs/src/system/system_param.rs

@@ -228,6 +228,8 @@ fn assert_component_access_compatibility(
     panic!("error[B0001]: Query<{query_type}, {filter_type}> in system {system_name} accesses component(s) {accesses} in a way that conflicts with a previous system parameter. Consider using `Without<T>` to create disjoint Queries or merging conflicting Queries into a `ParamSet`.");
 }
 
+// SAFETY: Relevant query ComponentId and ArchetypeComponentId access is applied to SystemMeta. If
+// this TermQuery conflicts with any prior access, a panic will occur.
 unsafe impl<Q: QueryTermGroup + 'static, F: QueryTermGroup + 'static> SystemParam
     for TermQuery<'_, '_, Q, F>
 {

crates/bevy_ecs/src/system/term_query.rs

@@ -17,10 +17,10 @@ use crate::{
 /// For more information on dynamically building a [`TermQuery`] see [`QueryBuilder`]
 ///
 /// [System parameter]: crate::system::SystemParam
-/// [`QueryBuilder`]: crate::term_query::QueryBuilder
-/// [`Query`]: crate::system::Query
-/// [`Component`]: crate::component::Component
-/// [`World`]: crate::World
+/// [`QueryBuilder`]: crate::prelude::QueryBuilder
+/// [`Query`]: crate::prelude::Query
+/// [`Component`]: crate::prelude::Component
+/// [`World`]: crate::prelude::World
 pub struct TermQuery<'w, 's, Q: QueryTermGroup, F: QueryTermGroup = ()> {
     // SAFETY: Must have access to the components registered in `state`.
     world: UnsafeWorldCell<'w>,
@@ -63,8 +63,7 @@ impl<'w, 's, Q: QueryTermGroup, F: QueryTermGroup> TermQuery<'w, 's, Q, F> {
     /// # See also
     ///
     /// - [`iter_mut`](Self::iter_mut) for mutable query items.
-    /// - [`for_each`](Self::for_each) for the closure based alternative.
-    /// - [`Query::iter`](crate::query::Query::iter) for more examples
+    /// - [`Query::iter`](crate::prelude::Query::iter) for more examples
     #[inline]
     pub fn iter(&self) -> TermQueryIter<'_, 's, Q::ReadOnly> {
         // SAFETY:
@@ -82,8 +81,7 @@ impl<'w, 's, Q: QueryTermGroup, F: QueryTermGroup> TermQuery<'w, 's, Q, F> {
     /// # See also
     ///
     /// - [`iter`](Self::iter) for read-only query items.
-    /// - [`for_each_mut`](Self::for_each_mut) for the closure based alternative.
-    /// - [`Query::iter_mut`](crate::query::Query::iter_mut) for more examples
+    /// - [`Query::iter_mut`](crate::prelude::Query::iter_mut) for more examples
     #[inline]
     pub fn iter_mut(&mut self) -> TermQueryIter<'_, 's, Q> {
         // SAFETY: `self.world` has permission to access the required components.
@@ -94,8 +92,8 @@ impl<'w, 's, Q: QueryTermGroup, F: QueryTermGroup> TermQuery<'w, 's, Q, F> {
     }
 
     /// Returns an untyped [`Iterator`] over the query items.
-    /// Provides access to a list of the [`Term`]s used to resolve this query as well as
-    /// a list of the resolved [`FetchedTerm`]
+    /// Provides access to a list of the [`Term`](crate::prelude::Term)s used to resolve this query as well as
+    /// a list of the resolved [`FetchedTerm`](crate::prelude::FetchedTerm)
     ///
     /// # Example
     ///
@@ -115,12 +113,12 @@ impl<'w, 's, Q: QueryTermGroup, F: QueryTermGroup> TermQuery<'w, 's, Q, F> {
     /// # struct C(usize);
     ///
     /// fn update_system(mut query: TermQuery<(&mut A, &B, &mut C)>) {
-    ///     query.iter_raw().for_each(|terms| {
-    ///         terms.for_each(|(term, fetch)| {
+    ///     query.iter_raw().for_each(|(terms, fetches)| {
+    ///         terms.iter().zip(fetches.iter()).for_each(|(term, fetch)| {
     ///             if term.access == TermAccess::Write {
-    ///                 // Since all the components have the same layout we can cast them all to the same value
-    ///                 let component = <mut &A>::from_fetch(fetch);
-    ///                 component += 1;
+    ///                 // SAFETY: Since all the components have the same layout we can cast them all to the same value
+    ///                 let mut component = unsafe { <&mut A>::from_fetch(fetch) };
+    ///                 component.0 += 1;
     ///             }
     ///         })
     ///     });
@@ -129,6 +127,7 @@ impl<'w, 's, Q: QueryTermGroup, F: QueryTermGroup> TermQuery<'w, 's, Q, F> {
     /// ```
     #[inline]
     pub fn iter_raw(&mut self) -> TermQueryIterUntyped<'_, 's> {
+        // SAFETY: `self.world` has permission to access the required components.
         unsafe {
             self.state
                 .iter_raw_manual(self.world, self.last_run, self.this_run)
@@ -142,7 +141,7 @@ impl<'w, 's, Q: QueryTermGroup, F: QueryTermGroup> TermQuery<'w, 's, Q, F> {
     /// # See also
     ///
     /// - [`get_mut`](Self::get_mut) to get a mutable query item.
-    /// - [`Query::get_mut`](crate::query::Query::get_mut) for more examples
+    /// - [`Query::get_mut`](crate::prelude::Query::get_mut) for more examples
     #[inline]
     pub fn get(&self, entity: Entity) -> Result<ROTermItem<'_, Q>, QueryEntityError> {
         // SAFETY: system runs without conflicts with other systems.
@@ -164,7 +163,7 @@ impl<'w, 's, Q: QueryTermGroup, F: QueryTermGroup> TermQuery<'w, 's, Q, F> {
     /// # See also
     ///
     /// - [`get`](Self::get) to get a read-only query item.
-    /// - [`Query::get`](crate::query::Query::get) for more examples
+    /// - [`Query::get`](crate::prelude::Query::get) for more examples
     #[inline]
     pub fn get_mut(&mut self, entity: Entity) -> Result<Q::Item<'_>, QueryEntityError> {
         // SAFETY: system runs without conflicts with other systems.
@@ -181,7 +180,7 @@ impl<'w, 's, Q: QueryTermGroup, F: QueryTermGroup> TermQuery<'w, 's, Q, F> {
     ///
     /// - [`get_single`](Self::get_single) for the non-panicking version.
     /// - [`single_mut`](Self::single_mut) to get the mutable query item.
-    /// - [`Query::single`](crate::query::Query::single) for more examples
+    /// - [`Query::single`](crate::prelude::Query::single) for more examples
     pub fn single(&self) -> ROTermItem<'_, Q> {
         self.get_single().unwrap()
     }
@@ -194,7 +193,7 @@ impl<'w, 's, Q: QueryTermGroup, F: QueryTermGroup> TermQuery<'w, 's, Q, F> {
     ///
     /// - [`get_single_mut`](Self::get_single_mut) to get the mutable query item.
     /// - [`single`](Self::single) for the panicking version.
-    /// - [`Query::get_single`](crate::query::Query::get_single) for more examples
+    /// - [`Query::get_single`](crate::prelude::Query::get_single) for more examples
     #[inline]
     pub fn get_single(&self) -> Result<ROTermItem<'_, Q>, QuerySingleError> {
         // SAFETY:
@@ -215,7 +214,7 @@ impl<'w, 's, Q: QueryTermGroup, F: QueryTermGroup> TermQuery<'w, 's, Q, F> {
     ///
     /// - [`get_single_mut`](Self::get_single_mut) for the non-panicking version.
     /// - [`single`](Self::single) to get the read-only query item.
-    /// - [`Query::single_mut`](crate::query::Query::single_mut) for more examples
+    /// - [`Query::single_mut`](crate::prelude::Query::single_mut) for more examples
     pub fn single_mut(&mut self) -> Q::Item<'_> {
         self.get_single_mut().unwrap()
     }
@@ -228,7 +227,7 @@ impl<'w, 's, Q: QueryTermGroup, F: QueryTermGroup> TermQuery<'w, 's, Q, F> {
     ///
     /// - [`get_single`](Self::get_single) to get the read-only query item.
     /// - [`single_mut`](Self::single_mut) for the panicking version.
-    /// - [`Query::get_single_mut`](crate::query::Query::get_single_mut) for more examples
+    /// - [`Query::get_single_mut`](crate::prelude::Query::get_single_mut) for more examples
     #[inline]
     pub fn get_single_mut(&mut self) -> Result<Q::Item<'_>, QuerySingleError> {
         // SAFETY:
@@ -246,6 +245,7 @@ impl<'w, 's, Q: QueryTermGroup, F: QueryTermGroup> IntoIterator for &'w TermQuer
     type IntoIter = TermQueryIter<'w, 's, Q::ReadOnly>;
 
     fn into_iter(self) -> Self::IntoIter {
+        // SAFETY: invariants guaranteed in TermQuery::new
         unsafe {
             TermQueryIter::new(
                 self.world,
@@ -264,6 +264,7 @@ impl<'w, 's, Q: QueryTermGroup, F: QueryTermGroup> IntoIterator
     type IntoIter = TermQueryIter<'w, 's, Q>;
 
     fn into_iter(self) -> Self::IntoIter {
+        // SAFETY: invariants guaranteed in TermQuery::new
         unsafe {
             TermQueryIter::new(
                 self.world,

crates/bevy_ecs/src/term_query/builder.rs

@@ -7,6 +7,17 @@ use super::{QueryTermGroup, Term, TermOperator, TermQueryState};
 /// Builder for [`TermQuery`](crate::system::TermQuery)
 ///
 /// ```
+/// use bevy_ecs::prelude::*;
+///
+/// #[derive(Component)]
+/// struct A(usize);
+///
+/// #[derive(Component)]
+/// struct B(usize);
+///
+/// #[derive(Component)]
+/// struct C(usize);
+///
 /// let mut world = World::new();
 /// let entity_a = world.spawn((A(0), B(0))).id();
 /// let entity_b = world.spawn((A(0), C(0))).id();
@@ -49,9 +60,10 @@ impl<'w, Q: QueryTermGroup> QueryBuilder<'w, Q> {
 
     /// Sets `current_term` to `index`
     ///
-    /// This is primarily intended for use with [`Self::set_dynamic`] and [`Self::set_dynamic_by_id].
+    /// This is primarily intended for use with [`Self::set_dynamic`] and [`Self::set_dynamic_by_id`].
     ///
-    /// SAFETY: terms must not be modified such that they become incompatible with Q
+    /// # Safety
+    /// Caller must not modify terms such that they become incompatible with Q
     pub unsafe fn term_at(&mut self, index: usize) -> &mut Self {
         self.current_term = index;
         self
@@ -105,7 +117,7 @@ impl<'w, Q: QueryTermGroup> QueryBuilder<'w, Q> {
 
     /// Takes a function over mutable access to a [`QueryBuilder`], calls that function
     /// on an empty builder and then adds all terms from that builder to self marked as
-    /// [`TermAccess::Optional`]
+    /// [`TermOperator::Optional`]
     pub fn optional(&mut self, f: impl Fn(&mut QueryBuilder)) -> &mut Self {
         let mut builder = QueryBuilder::new(self.world);
         f(&mut builder);
@@ -147,7 +159,7 @@ impl<'w, Q: QueryTermGroup> QueryBuilder<'w, Q> {
 
     /// Set the [`ComponentId`] of the term indexed by `current_term` to the one associated with `T`
     ///
-    /// Intended to be used primarily with queries with [`Ptr`] terms
+    /// Intended to be used primarily with queries with [`Ptr`](bevy_ptr::Ptr) terms
     pub fn set_dynamic<T: Component>(&mut self) -> &mut Self {
         let id = self.world.init_component::<T>();
         self.set_dynamic_by_id(id);
@@ -156,7 +168,7 @@ impl<'w, Q: QueryTermGroup> QueryBuilder<'w, Q> {
 
     /// Set the [`ComponentId`] of the term indexed by `current_term`
     ///
-    /// Intended to be used primarily with queries with [`Ptr`] terms
+    /// Intended to be used primarily with queries with [`Ptr`](bevy_ptr::Ptr) terms
     pub fn set_dynamic_by_id(&mut self, id: ComponentId) -> &mut Self {
         self.terms[self.current_term].component = Some(id);
         self
@@ -178,8 +190,9 @@ impl<'w, Q: QueryTermGroup> QueryBuilder<'w, Q> {
     }
 
     /// Attempts to re-interpret this builder as [`QueryBuilder<NewQ>`]
-    pub fn try_transmute<NewQ: QueryTermGroup>(mut self) -> Option<QueryBuilder<'w, NewQ>> {
+    pub fn try_transmute<NewQ: QueryTermGroup>(&mut self) -> Option<&mut QueryBuilder<'w, NewQ>> {
         if self.interpretable_as::<NewQ>() {
+            // SAFETY: Just checked that NewQ is compatible with Q
             Some(unsafe { std::mem::transmute(self) })
         } else {
             None
@@ -188,7 +201,9 @@ impl<'w, Q: QueryTermGroup> QueryBuilder<'w, Q> {
 
     /// Re-interprets this builder as [`QueryBuilder<NewQ>`]
     ///
-    /// SAFETY: Caller must ensure that [`Self::interpretable_as::<NewQ>()`] is true
+    /// # Safety
+    ///
+    /// Caller must ensure that [`Self::interpretable_as::<NewQ>()`] is true
     pub unsafe fn transmute<NewQ: QueryTermGroup>(self) -> QueryBuilder<'w, NewQ> {
         std::mem::transmute(self)
     }

crates/bevy_ecs/src/term_query/iter.rs

@@ -114,7 +114,7 @@ impl<'w, 's> TermQueryCursor<'w, 's> {
 
                 let entity = archetype_entity.entity();
                 let row = archetype_entity.table_row();
-                if query_state.filter_fetch(&mut self.term_state, entity, row) {
+                if query_state.filter_fetch(&self.term_state, entity, row) {
                     return Some(query_state.fetch(
                         &self.term_state,
                         entity,
@@ -162,6 +162,9 @@ impl<'w, 's> Iterator for TermQueryIterUntyped<'w, 's> {
 
     #[inline]
     fn next(&mut self) -> Option<Self::Item> {
+        // SAFETY:
+        // `tables` and `archetypes` belong to the same world that the cursor was initialized for.
+        // `query_state` is the state that was passed to `TermQueryCursor::new`.
         unsafe {
             self.cursor
                 .next(self.tables, self.archetypes, self.query_state)
@@ -210,14 +213,9 @@ impl<'w, 's, Q: QueryTermGroup> Iterator for TermQueryIter<'w, 's, Q> {
         // `tables` and `archetypes` belong to the same world that the cursor was initialized for.
         // `query_state` is the state that was passed to `QueryIterationCursor::init`.
         unsafe {
-            if let Some(fetches) = self
-                .cursor
+            self.cursor
                 .next(self.tables, self.archetypes, self.query_state)
-            {
-                Some(Q::from_fetches(&mut fetches.iter()))
-            } else {
-                None
-            }
+                .map(|fetches| Q::from_fetches(&mut fetches.iter()))
         }
     }
 }