diff --git a/crates/bevy_ecs/src/component.rs b/crates/bevy_ecs/src/component.rs index 054d2d3f7d9a2..9ef97a2eebbb2 100644 --- a/crates/bevy_ecs/src/component.rs +++ b/crates/bevy_ecs/src/component.rs @@ -138,13 +138,20 @@ impl ComponentInfo { } } -/// A [`ComponentId`] is an 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 +/// A [`ComponentId`] is an 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. /// +/// 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 +/// 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 /// of a [`Component`] in a different [`World`](crate::world::World) is undefined behaviour and should @@ -364,7 +371,9 @@ impl Components { } /// Retrieves the [`ComponentId`] of the given [`Component`] type in - /// this [`Components`] instance. Returns [`None`] if the [`Component`] type has not + /// this [`Components`] instance. + /// + /// Returns [`None`] if the [`Component`] type has not /// yet been initialized using [`Components::init_component`]. /// ```rust /// use bevy_ecs::prelude::*; diff --git a/crates/bevy_ecs/src/world/mod.rs b/crates/bevy_ecs/src/world/mod.rs index 9387af8370b57..e77bb9d062158 100644 --- a/crates/bevy_ecs/src/world/mod.rs +++ b/crates/bevy_ecs/src/world/mod.rs @@ -184,11 +184,12 @@ impl World { } /// Initializes a new Component type within this [`World`] and returns the - /// [`ComponentId`] assigned to 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. + /// [`ComponentId`] assigned to 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. /// /// While [`World::init_component_with_descriptor`] is useful in type-erased contexts, /// the standard [`World::init_component`] function should always be used instead @@ -202,7 +203,9 @@ impl World { } /// Retrieves the [`ComponentId`] of the given [`Component`] type in - /// this [`World`]. Returns [`None`] if the [`Component`] type has not + /// this [`World`]. + /// + /// Returns [`None`] if the [`Component`] type has not /// yet been initialized within the [`World`] using [`World::init_component`]. /// ```rust /// use bevy_ecs::prelude::*;