Address document feedback round #2

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::<ComponentA>();
     ///
-    ///assert_eq!(component_a_id, world.components().component_id::<ComponentA>().unwrap())
+    /// assert_eq!(component_a_id, world.components().component_id::<ComponentA>().unwrap())
     /// ```
     #[inline]
     pub fn component_id<T: Component>(&self) -> Option<ComponentId> {

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<T: Component>(&mut self) -> ComponentId {
         self.components.init_component::<T>(&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::<ComponentA>();
     ///
-    ///assert_eq!(component_a_id, world.component_id::<ComponentA>().unwrap())
+    /// assert_eq!(component_a_id, world.component_id::<ComponentA>().unwrap())
     /// ```
     #[inline]
     pub fn component_id<T: Component>(&self) -> Option<ComponentId> {