diff --git a/crates/bevy_ecs/src/entity/mod.rs b/crates/bevy_ecs/src/entity/mod.rs index 2cf56b9dfb..1464a9e730 100644 --- a/crates/bevy_ecs/src/entity/mod.rs +++ b/crates/bevy_ecs/src/entity/mod.rs @@ -418,7 +418,7 @@ impl EntityGeneration { /// Aliasing can happen without warning. /// Holding onto a [`Entity`] id corresponding to an entity well after that entity was despawned can cause un-intuitive behavior for both ordering, and comparing in general. /// To prevent these bugs, it is generally best practice to stop holding an [`Entity`] or [`EntityGeneration`] value as soon as you know it has been despawned. -/// If you must do otherwise, do not assume the [`Entity`] corresponds to the same conceptual entity it originally did. +/// If you must do otherwise, do not assume the [`Entity`] id corresponds to the same entity it originally did. /// See [`EntityGeneration`]'s docs for more information about aliasing and why it occurs. /// /// # Stability warning @@ -1344,11 +1344,12 @@ pub struct EntityLocation { pub table_row: TableRow, } -/// An [`Entity`] id may or may not correspond to a valid conceptual entity. -/// If it does, the conceptual entity may or may not have a location. +/// An [`Entity`] id may or may not correspond to an entity; the entity may have been despawned, etc. +/// If it does correspond to an entity, that entity may or may not have a location. /// If it has no location, the [`EntityLocation`] will be `None`. /// An location of `None` means the entity effectively does not exist; it has an id, but is not participating in the ECS. /// This is different from a location in the empty archetype, which is participating (queryable, etc) but just happens to have no components. +/// For more information about what a `None` location means, see the module [docs](crate::entity). /// /// Setting a location to `None` is often helpful when you want to destruct an entity or yank it from the ECS without allowing another system to reuse the id for something else. /// It is also useful for reserving an id; commands will often allocate an `Entity` but not provide it a location until the command is applied. diff --git a/crates/bevy_ecs/src/world/mod.rs b/crates/bevy_ecs/src/world/mod.rs index c14503786d..c899f979b2 100644 --- a/crates/bevy_ecs/src/world/mod.rs +++ b/crates/bevy_ecs/src/world/mod.rs @@ -1063,10 +1063,11 @@ impl World { (fetcher, commands) } - /// Spawns an [`Entity`] that is void/null. - /// The returned entity id is valid and unique, but it does not correspond to any conceptual entity yet. - /// The conceptual entity does not exist, and using the id as if it did may produce errors. + /// Spawns an [`Entity`] that is null. + /// The returned entity id is valid and unique, but it is not yet constructed. + /// Using the id as if it were constructed may produce errors. /// It can not be queried, and it has no [`EntityLocation`](crate::entity::EntityLocation). + /// See [entity docs](crate::entity) for more information about null entities and construction. /// /// This is different from empty entities, which do exist in the world; /// they just happen to have no components.