From ab8cfc44c45bb375ed8a60533f59f2cbee1ee1a5 Mon Sep 17 00:00:00 2001
From: Garett Cooper <garett@garettcooper.com>
Date: Tue, 21 Jun 2022 23:31:32 -0400
Subject: [PATCH] Address documentation feedback

---
 crates/bevy_ecs/src/component.rs | 19 ++++++++++++++-----
 crates/bevy_ecs/src/world/mod.rs | 15 +++++++++------
 2 files changed, 23 insertions(+), 11 deletions(-)

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::*;