From ad5120ecfd868aa8e7ac68413f8d8bb7a38f524b Mon Sep 17 00:00:00 2001 From: Garett Cooper Date: Wed, 22 Jun 2022 19:51:06 -0400 Subject: [PATCH] Address document feedback round #2 --- crates/bevy_ecs/src/component.rs | 27 +++++++++++++++------------ crates/bevy_ecs/src/world/mod.rs | 29 ++++++++++++++--------------- 2 files changed, 29 insertions(+), 27 deletions(-) diff --git a/crates/bevy_ecs/src/component.rs b/crates/bevy_ecs/src/component.rs index 9ef97a2eebbb29..516a54c982becc 100644 --- a/crates/bevy_ecs/src/component.rs +++ b/crates/bevy_ecs/src/component.rs @@ -138,22 +138,22 @@ impl ComponentInfo { } } -/// A [`ComponentId`] is an semi-opaque value which uniquely identifies the type of -/// a [`Component`] within a [`World`](crate::world::World). +/// A semi-opaque value which uniquely identifies the type of a [`Component`] within a +/// [`World`](crate::world::World). /// /// Each time a new [`Component`] type is registered within a [`World`](crate::world::World) /// using [`World::init_component`](crate::world::World::init_component) or /// [`World::init_component_with_descriptor`](crate::world::World::init_component_with_descriptor), -/// a corresponding [`ComponentId`] is created to track it. +/// a corresponding `ComponentId` is created to track it. /// -/// While the distinction between [`ComponentId`] and [`TypeId`] may seem superficial, breaking them -/// in to two separate but related concepts allows Bevy components to exist outside of Rust's type system. -/// Each Rust type registered as a [`Component`] will have a corresponding [`ComponentId`], but additional -/// [`ComponentId`]s may exist in a [`World`](crate::world::World) to track components which cannot be +/// While the distinction between `ComponentId` and [`TypeId`] may seem superficial, breaking them +/// into two separate but related concepts allows components to exist outside of Rust's type system. +/// Each Rust type registered as a [`Component`] will have a corresponding `ComponentId`, but additional +/// `ComponentId`s may exist in a [`World`](crate::world::World) to track components which cannot be /// represented as Rust types for scripting or other advanced use-cases. /// -/// A [`ComponentId`] is tightly coupled to its parent [`World`](crate::world::World). -/// Attempting to use a [`ComponentId`] from one [`World`](crate::world::World) to access the metadata +/// A `ComponentId` is tightly coupled to its parent [`World`](crate::world::World). +/// Attempting to use a `ComponentId` from one [`World`](crate::world::World) to access the metadata /// of a [`Component`] in a different [`World`](crate::world::World) is undefined behaviour and should /// not be attempted. #[derive(Debug, Copy, Clone, Hash, Ord, PartialOrd, Eq, PartialEq)] @@ -370,11 +370,14 @@ impl Components { self.indices.get(&type_id).map(|index| ComponentId(*index)) } - /// Retrieves the [`ComponentId`] of the given [`Component`] type in - /// this [`Components`] instance. + /// Retrieves the [`ComponentId`] of the given [`Component`] type `T`. + /// The returned [`ComponentId`] is specific to the `Components` instance + /// it was retrieved from and should not be used with another `Components` + /// instance. /// /// Returns [`None`] if the [`Component`] type has not /// yet been initialized using [`Components::init_component`]. + /// /// ```rust /// use bevy_ecs::prelude::*; /// @@ -385,7 +388,7 @@ impl Components { /// /// let component_a_id = world.init_component::(); /// - ///assert_eq!(component_a_id, world.components().component_id::().unwrap()) + /// assert_eq!(component_a_id, world.components().component_id::().unwrap()) /// ``` #[inline] pub fn component_id(&self) -> Option { diff --git a/crates/bevy_ecs/src/world/mod.rs b/crates/bevy_ecs/src/world/mod.rs index e77bb9d0621589..9607c0a0bae44e 100644 --- a/crates/bevy_ecs/src/world/mod.rs +++ b/crates/bevy_ecs/src/world/mod.rs @@ -177,22 +177,19 @@ impl World { WorldCell::new(self) } - /// Initializes a new [`Component`] type within this [`World`] and returns the - /// [`ComponentId`] assigned to it. + /// Initializes a new [`Component`] and returns the [`ComponentId`] created for it. pub fn init_component(&mut self) -> ComponentId { self.components.init_component::(&mut self.storages) } - /// Initializes a new Component type within this [`World`] and returns the - /// [`ComponentId`] assigned to it. + /// Initializes a new Component type and returns the [`ComponentId`] created for it. /// - /// [`World::init_component_with_descriptor`] differs from [`World::init_component`] in - /// that it uses a [`ComponentDescriptor`] to initialize the new component type instead - /// of statically available type information. This enables the dynamic initialization of - /// new component definitions at runtime for advanced use cases. + /// This method differs from [`World::init_component`] in that it uses a [`ComponentDescriptor`] + /// to initialize the new component type instead of statically available type information. This + /// enables the dynamic initialization of new component definitions at runtime for advanced use cases. /// - /// While [`World::init_component_with_descriptor`] is useful in type-erased contexts, - /// the standard [`World::init_component`] function should always be used instead + /// While the option to initialize a component from a descriptor is useful in type-erased + /// contexts, the standard [`World::init_component`] function should always be used instead /// when type information is available at compile time. pub fn init_component_with_descriptor( &mut self, @@ -202,11 +199,13 @@ impl World { .init_component_with_descriptor(&mut self.storages, descriptor) } - /// Retrieves the [`ComponentId`] of the given [`Component`] type in - /// this [`World`]. + /// Retrieves the [`ComponentId`] of the given [`Component`] type `T`. The returned + /// [`ComponentId`] is specific to the `World` instance it was retrieved from and + /// should not be used with another `World` instance. + /// + /// Returns [`None`] if the [`Component`] type has not yet been initialized within + /// the [`World`] using [`World::init_component`]. /// - /// Returns [`None`] if the [`Component`] type has not - /// yet been initialized within the [`World`] using [`World::init_component`]. /// ```rust /// use bevy_ecs::prelude::*; /// @@ -217,7 +216,7 @@ impl World { /// /// let component_a_id = world.init_component::(); /// - ///assert_eq!(component_a_id, world.component_id::().unwrap()) + /// assert_eq!(component_a_id, world.component_id::().unwrap()) /// ``` #[inline] pub fn component_id(&self) -> Option {