Documentation for querying archetype claims.

src/query/result/archetype_identifiers.rs → src/query/result/archetype_claims.rs

@@ -1,3 +1,5 @@
+//! Iterator over dynamic claims of a query on its affected archetypes.
+
 use crate::{
     archetype,
     archetypes,
@@ -16,7 +18,11 @@ use crate::{
 };
 use core::marker::PhantomData;
 
-pub struct ArchetypeIdentifiers<'a, R, F, FI, V, VI, P, I, Q>
+/// Iterator over dynamic claims of a query on its affected archetypes.
+///
+/// This iterator returns key-value pairs of archetype identifiers and the list of claimed
+/// components for the given query on that archetype.
+pub struct ArchetypeClaims<'a, R, F, FI, V, VI, P, I, Q>
 where
     R: Registry,
 {
@@ -31,11 +37,13 @@ where
     reshape_indices: PhantomData<Q>,
 }
 
-impl<'a, R, F, FI, V, VI, P, I, Q> ArchetypeIdentifiers<'a, R, F, FI, V, VI, P, I, Q>
+impl<'a, R, F, FI, V, VI, P, I, Q> ArchetypeClaims<'a, R, F, FI, V, VI, P, I, Q>
 where
     R: Registry,
 {
-    /// # SAFETY
+    /// Returns a new `ArchetypeClaims` iterator.
+    ///
+    /// # Safety
     /// The `archetype::IdentifierRef`s over which this iterator iterates must not outlive the
     /// `Archetypes` to which they belong.
     pub(crate) unsafe fn new(archetypes_iter: archetypes::IterMut<'a, R>) -> Self {
@@ -53,7 +61,7 @@ where
     }
 }
 
-impl<'a, R, F, FI, V, VI, P, I, Q> Iterator for ArchetypeIdentifiers<'a, R, F, FI, V, VI, P, I, Q>
+impl<'a, R, F, FI, V, VI, P, I, Q> Iterator for ArchetypeClaims<'a, R, F, FI, V, VI, P, I, Q>
 where
     F: Filter,
     V: Views<'a> + Filter,

src/query/result/mod.rs

@@ -50,7 +50,7 @@
 //! [`World`]: crate::world::World
 
 #[cfg(feature = "rayon")]
-pub(crate) mod archetype_identifiers;
+pub(crate) mod archetype_claims;
 pub(crate) mod get;
 pub(crate) mod reshape;
 
@@ -64,7 +64,7 @@ pub use iter::Iter;
 pub use par_iter::ParIter;
 
 #[cfg(feature = "rayon")]
-pub(crate) use archetype_identifiers::ArchetypeIdentifiers;
+pub(crate) use archetype_claims::ArchetypeClaims;
 pub(crate) use get::Get;
 pub(crate) use reshape::Reshape;
 #[cfg(feature = "rayon")]

src/system/schedule/stage.rs

@@ -125,7 +125,7 @@ where
         // SAFETY: The access to the world's archetype identifiers follows Rust's borrowing
         // rules.
         unsafe {
-            (*world.get()).query_archetype_identifiers(Query::<T::Views, T::Filter>::new())
+            (*world.get()).query_archetype_claims(Query::<T::Views, T::Filter>::new())
         }
     {
         match merged_borrowed_archetypes.entry(identifier) {
@@ -157,7 +157,7 @@ fn query_archetype_identifiers_unchecked<'a, R, T, FI, VI, P, I, Q>(
         // SAFETY: The access to the world's archetype identifiers follows Rust's borrowing
         // rules.
         unsafe {
-            (*world.get()).query_archetype_identifiers(Query::<T::Views, T::Filter>::new())
+            (*world.get()).query_archetype_claims(Query::<T::Views, T::Filter>::new())
         }
     {
         borrowed_archetypes.insert_unique_unchecked(identifier, claims);

src/world/mod.rs

@@ -360,22 +360,24 @@ where
         result::ParIter::new(self.archetypes.par_iter_mut())
     }
 
+    /// Return the claims on each archetype touched by the given query.
+    ///
     /// # Safety
     /// The `archetype::IdentifierRef`s over which this iterator iterates must not outlive the
     /// `Archetypes` to which they belong.
     #[cfg(feature = "rayon")]
     #[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))]
-    pub(crate) unsafe fn query_archetype_identifiers<'a, V, F, VI, FI, P, I, Q>(
+    pub(crate) unsafe fn query_archetype_claims<'a, V, F, VI, FI, P, I, Q>(
         &'a mut self,
         #[allow(unused_variables)] query: Query<V, F>,
-    ) -> result::ArchetypeIdentifiers<'a, R, F, FI, V, VI, P, I, Q>
+    ) -> result::ArchetypeClaims<'a, R, F, FI, V, VI, P, I, Q>
     where
         V: Views<'a> + Filter,
         F: Filter,
         R: ContainsFilter<And<F, V>, And<FI, VI>>,
     {
         // SAFETY: The safety contract here is upheld by the safety contract of this method.
-        unsafe { result::ArchetypeIdentifiers::new(self.archetypes.iter_mut()) }
+        unsafe { result::ArchetypeClaims::new(self.archetypes.iter_mut()) }
     }
 
     /// Run a [`System`] over the entities in this `World`.