More suggestions from review

Co-Authored-By: urben1680 <55257931+urben1680@users.noreply.github.com>

crates/bevy_ecs/src/entity/mod.rs

@@ -817,6 +817,10 @@ impl EntitiesAllocator {
         *self.next_row.get_mut() = 0;
     }
 
+    /// This allows `freed` to be retrieved from [`alloc`](Self::alloc), etc.
+    /// Freeing an [`Entity`] such that one [`EntityRow`] is in the allocator in multiple places can cause panics when spawning the allocated entity.
+    /// Additionally, to differentiate versions of an [`Entity`], updating the [`EntityGeneration`] before freeing is a good idea
+    /// (but not strictly necessary if you don't mind [`Entity`] id aliasing.)
     pub(crate) fn free(&mut self, freed: Entity) {
         let expected_len = *self.free_len.get_mut() as usize;
         if expected_len > self.free.len() {
@@ -1029,7 +1033,7 @@ impl Entities {
     /// This can error if the entity does not exist or if it is already constructed.
     /// See the module docs for a more precise explanation of which entities exist and what construction means.
     #[inline]
-    pub fn validate_construction(&self, entity: Entity) -> Result<(), ConstructionError> {
+    pub fn is_id_safe_to_construct(&self, entity: Entity) -> Result<(), ConstructionError> {
         match self.get(entity) {
             Ok(Some(_)) => Err(ConstructionError::AlreadyConstructed),
             Ok(None) => Ok(()),

crates/bevy_ecs/src/world/mod.rs

@@ -1130,7 +1130,7 @@ impl World {
         bundle: B,
         caller: MaybeLocation,
     ) -> Result<EntityWorldMut<'_>, ConstructionError> {
-        self.entities.validate_construction(entity)?;
+        self.entities.is_id_safe_to_construct(entity)?;
         Ok(self.construct_unchecked(entity, bundle, caller))
     }
 
@@ -1182,7 +1182,7 @@ impl World {
         entity: Entity,
         caller: MaybeLocation,
     ) -> Result<EntityWorldMut<'_>, ConstructionError> {
-        self.entities.validate_construction(entity)?;
+        self.entities.is_id_safe_to_construct(entity)?;
         Ok(self.construct_empty_unchecked(entity, caller))
     }
 

release-content/migration-guides/entities_apis.md

@@ -6,6 +6,7 @@ pull_requests: [19350, 19433, 19451]
 In 0.16, entities could have zero or more components.
 In 0.17, a new state for an entity is introduced: null/not constructed.
 Entities can now be constructed and destructed within their spawned life cycle.
+For a full explanation of the new entity life cycle, see the new `entity` module docs.
 This opens up a lot of room for performance improvement but also caused a lot of breaking changes:
 
 ### `Entities` rework