don't use entity_ref::* import in world.rs to distinguish public and private imports, add safety comments

Author: jakobhellermann

crates/bevy_ecs/src/world/entity_ref.rs

@@ -808,15 +808,18 @@ fn sorted_remove<T: Eq + Ord + Copy>(source: &mut Vec<T>, remove: &[T]) {
 
 // SAFETY: EntityLocation must be valid
 #[inline]
-pub(crate) unsafe fn get_mut<T: Component>(
-    world: &mut World,
+pub(crate) unsafe fn get_mut<'w, T: Component>(
+    world: &'w mut World,
     entity: Entity,
     location: EntityLocation,
-) -> Option<Mut<'_, T>> {
-    // SAFETY: world access is unique, entity location is valid, and returned component is of type
-    // T
+) -> Option<Mut<'w, T>> {
     let change_tick = world.change_tick();
     let last_change_tick = world.last_change_tick();
+    // SAFETY:
+    // - world access is unique
+    // - entity location is valid
+    // - and returned component is of type T
+    // - archetypes and components comes from the same world
     world
         .storages
         .get_component_and_ticks_with_type(
@@ -827,8 +830,12 @@ pub(crate) unsafe fn get_mut<T: Component>(
             location,
         )
         .map(|(value, ticks)| Mut {
+            // SAFETY:
+            // - world access is unique and ties world lifetime to `Mut` lifetime
+            // - `value` is of type `T`
             value: value.assert_unique().deref_mut::<T>(),
             ticks: Ticks {
+                // SAFETY:  world access is unique and ties world lifetime to `Mut` lifetime
                 component_ticks: ticks.deref_mut(),
                 last_change_tick,
                 change_tick,
@@ -844,7 +851,11 @@ pub(crate) unsafe fn get_mut_by_id(
     location: EntityLocation,
     component_id: ComponentId,
 ) -> Option<MutUntyped> {
-    // SAFETY: world access is unique, entity location and component_id required to be valid
+    // SAFETY:
+    // - world access is unique
+    // - entity location is valid
+    // - and returned component is of type T
+    // - archetypes and components comes from the same world
     world
         .storages
         .get_component_and_ticks(
@@ -855,8 +866,10 @@ pub(crate) unsafe fn get_mut_by_id(
             location,
         )
         .map(|(value, ticks)| MutUntyped {
+            // SAFETY: world access is unique and ties world lifetime to `MutUntyped` lifetime
             value: value.assert_unique(),
             ticks: Ticks {
+                // SAFETY:  world access is unique and ties world lifetime to `Mut` lifetime
                 component_ticks: ticks.deref_mut(),
                 last_change_tick: world.last_change_tick(),
                 change_tick: world.read_change_tick(),

crates/bevy_ecs/src/world/mod.rs

@@ -3,7 +3,7 @@ mod spawn_batch;
 mod world_cell;
 
 pub use crate::change_detection::Mut;
-pub use entity_ref::*;
+pub use entity_ref::{EntityMut, EntityRef};
 pub use spawn_batch::*;
 pub use world_cell::*;
 
@@ -557,8 +557,10 @@ impl World {
     /// ```
     #[inline]
     pub fn get_mut<T: Component>(&mut self, entity: Entity) -> Option<Mut<T>> {
-        // SAFETY: lifetimes enforce correct usage of returned borrow
-        unsafe { get_mut(self, entity, self.get_entity(entity)?.location()) }
+        // SAFETY:
+        // - lifetimes enforce correct usage of returned borrow
+        // - entity location is checked in `get_entity`
+        unsafe { entity_ref::get_mut(self, entity, self.get_entity(entity)?.location()) }
     }
 
     /// Despawns the given `entity`, if it exists. This will also remove all of the entity's
@@ -1527,7 +1529,7 @@ impl World {
         self.components().get_info(component_id)?;
         // SAFETY: entity_location is valid, component_id is valid as checked by the line above
         unsafe {
-            get_mut_by_id(
+            entity_ref::get_mut_by_id(
                 self,
                 entity,
                 self.get_entity(entity)?.location(),