documentation

Author: jrobsonchase

crates/bevy_ecs/src/entity/map_entities.rs

@@ -6,42 +6,30 @@ use crate::{
 
 use super::EntityHashMap;
 
-/// Operation to map all contained [`Entity`] fields in a type to new values.
+/// Apply an operation to all entities in a read-only container.
 ///
-/// As entity IDs are valid only for the [`World`] they're sourced from, using [`Entity`]
-/// as references in components copied from another world will be invalid. This trait
-/// allows defining custom mappings for these references via [`EntityMappers`](EntityMapper), which
-/// inject the entity mapping strategy between your `MapEntities` type and the current world
-/// (usually by using an [`EntityHashMap<Entity>`] between source entities and entities in the
-/// current world).
+/// This is implemented by default for types that implement [`IterEntities`] or
+/// where `&T` implements [`IntoIterator`].
 ///
-/// Implementing this trait correctly is required for properly loading components
-/// with entity references from scenes.
-///
-/// ## Example
-///
-/// ```
-/// use bevy_ecs::prelude::*;
-/// use bevy_ecs::entity::MapEntities;
-///
-/// #[derive(Component)]
-/// struct Spring {
-///     a: Entity,
-///     b: Entity,
-/// }
-///
-/// impl MapEntities for Spring {
-///     fn map_entities<M: EntityMapper>(&mut self, entity_mapper: &mut M) {
-///         self.a = entity_mapper.map_entity(self.a);
-///         self.b = entity_mapper.map_entity(self.b);
-///     }
-/// }
-/// ```
+/// It may be useful to implement directly for types that can't produce an
+/// iterator for lifetime reasons, such as those involving internal mutexes.
 pub trait MapEntities {
+    /// Apply an operation to all contained entities.
     fn map_entities<F: FnMut(Entity)>(&self, f: F);
 }
 
+/// Apply an operation to mutable references to all entities in a container.
+///
+/// This is implemented by default for types that implement [`IterEntitiesMut`]
+/// or where `&mut T` implements [`IntoIterator`].
+///
+/// It may be useful to implement directly for types that can't produce an
+/// iterator for lifetime reasons, such as those involving internal mutexes.
+///
+/// Because the operation receives mutable references, it may alter the
+/// contained entity IDs via a mechanism such as an [`EntityMapper`].
 pub trait MapEntitiesMut: MapEntities {
+    /// Apply an operation to mutable references to all entities.
     fn map_entities_mut<F: FnMut(&mut Entity)>(&mut self, f: F);
 }
 
@@ -63,7 +51,15 @@ where
     }
 }
 
+/// Produce an iterator over all contained entities.
+///
+/// This is implemented by default for types  where `&T` implements
+/// [`IntoIterator`].
+///
+/// It may be useful to implement directly for types that can't produce an
+/// iterator for lifetime reasons, such as those involving internal mutexes.
 pub trait IterEntities {
+    /// Get an iterator over contained entities.
     fn iter_entities(&self) -> impl Iterator<Item = Entity>;
 }
 
@@ -76,7 +72,18 @@ where
     }
 }
 
+/// Apply an operation to mutable references to all entities in a container.
+///
+/// This is implemented by default for types where `&mut T` implements
+/// [`IntoIterator`].
+///
+/// It may be useful to implement directly for types that can't produce an
+/// iterator for lifetime reasons, such as those involving internal mutexes.
+///
+/// Because the iterator produces mutable references, consumers may alter the
+/// contained entity IDs via a mechanism such as an [`EntityMapper`].
 pub trait IterEntitiesMut: IterEntities {
+    /// Get an iterator over mutable references to contained entities.
     fn iter_entities_mut(&mut self) -> impl Iterator<Item = &mut Entity>;
 }
 

crates/bevy_ecs/src/reflect/map_entities.rs

@@ -24,10 +24,11 @@ impl ReflectMapEntities {
     ///
     /// Be mindful in its usage: Works best in situations where the entities in the [`EntityHashMap<Entity>`] are newly
     /// created, before systems have a chance to add new components. If some of the entities referred to
-    /// by the [`EntityHashMap<Entity>`] might already contain valid entity references, you should use [`map_entities`](Self::map_entities).
+    /// by the [`EntityHashMap<Entity>`] might already contain valid entity references, you should use
+    /// [`map_world_entities`](Self::map_entities).
     ///
     /// An example of this: A scene can be loaded with `Parent` components, but then a `Parent` component can be added
-    /// to these entities after they have been loaded. If you reload the scene using [`map_all_entities`](Self::map_all_entities), those `Parent`
+    /// to these entities after they have been loaded. If you reload the scene using [`map_all_world_entities`](Self::map_all_world_entities), those `Parent`
     /// components with already valid entity references could be updated to point at something else entirely.
     pub fn map_all_world_entities(
         &self,
@@ -38,11 +39,11 @@ impl ReflectMapEntities {
     }
 
     /// A general method for applying [`MapEntities`] behavior to elements in an [`EntityHashMap<Entity>`]. Unlike
-    /// [`map_all_entities`](Self::map_all_entities), this is applied to specific entities, not all values
+    /// [`map_all_world_entities`](Self::map_all_world_entities), this is applied to specific entities, not all values
     /// in the [`EntityHashMap<Entity>`].
     ///
     /// This is useful mostly for when you need to be careful not to update components that already contain valid entity
-    /// values. See [`map_all_entities`](Self::map_all_entities) for more details.
+    /// values. See [`map_all_world_entities`](Self::map_all_world_entities) for more details.
     pub fn map_world_entities(
         &self,
         world: &mut World,
@@ -54,10 +55,14 @@ impl ReflectMapEntities {
         });
     }
 
+    /// A general method for applying an operation to all entities in a
+    /// reflected component.
     pub fn map_entities(&self, component: &dyn PartialReflect, f: &mut dyn FnMut(Entity)) {
         (self.map_entities)(component, f)
     }
 
+    /// A general method for applying an operation that may modify entities in a
+    /// reflected component.
     pub fn map_entities_mut(
         &self,
         component: &mut dyn PartialReflect,