From be039c61c87b7c19f019b64ea3be3427c29a00d5 Mon Sep 17 00:00:00 2001
From: Gino Valente <gino.valente.code@gmail.com>
Date: Tue, 30 Aug 2022 21:46:30 -0700
Subject: [PATCH] Update documentation for Reflectable

---
 crates/bevy_reflect/src/lib.rs           | 2 +-
 crates/bevy_reflect/src/reflect.rs       | 6 ++++++
 crates/bevy_reflect/src/type_info.rs     | 3 +++
 crates/bevy_reflect/src/type_registry.rs | 4 ++++
 4 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/crates/bevy_reflect/src/lib.rs b/crates/bevy_reflect/src/lib.rs
index d1e07bbae58c0c..1fea6cffaf3547 100644
--- a/crates/bevy_reflect/src/lib.rs
+++ b/crates/bevy_reflect/src/lib.rs
@@ -59,7 +59,7 @@ pub use type_info::*;
 pub use type_registry::*;
 pub use type_uuid::*;
 
-/// A catch-all trait bound by the core reflection traits for easy reflection-based trait bounds.
+/// A catch-all trait, bound by the core reflection traits for easy reflection-based trait bounds.
 ///
 /// You do _not_ need to implement this trait manually.
 /// It is automatically implemented for all types that implement its supertraits.
diff --git a/crates/bevy_reflect/src/reflect.rs b/crates/bevy_reflect/src/reflect.rs
index fb8285fd9de0c3..5bbb671195ea7e 100644
--- a/crates/bevy_reflect/src/reflect.rs
+++ b/crates/bevy_reflect/src/reflect.rs
@@ -52,6 +52,12 @@ pub enum ReflectMut<'a> {
 ///
 /// When using `#[derive(Reflect)]` on a struct, tuple struct or enum, the suitable subtrait for that
 /// type (`Struct`, `TupleStruct` or `Enum`) is derived automatically.
+///
+/// Typically, generic types will require that their generic arguments be bound by `Reflect`, among
+/// other reflection traits. In these cases, it's recommended to use the [`Reflectable`] trait to
+/// cover all the necessary bounds.
+///
+/// [`Reflectable`]: crate::Reflectable
 pub trait Reflect: Any + Send + Sync {
     /// Returns the [type name][std::any::type_name] of the underlying type.
     fn type_name(&self) -> &str;
diff --git a/crates/bevy_reflect/src/type_info.rs b/crates/bevy_reflect/src/type_info.rs
index 9e5519d500ad62..9c44084412559f 100644
--- a/crates/bevy_reflect/src/type_info.rs
+++ b/crates/bevy_reflect/src/type_info.rs
@@ -8,6 +8,8 @@ use std::any::{Any, TypeId};
 /// This trait is automatically implemented by the `#[derive(Reflect)]` macro
 /// and allows type information to be processed without an instance of that type.
 ///
+/// As a core trait to the reflection system, it is a supertrait of [`Reflectable`].
+///
 /// # Implementing
 ///
 /// While it is recommended to leave implementing this trait to the `#[derive(Reflect)]` macro,
@@ -63,6 +65,7 @@ use std::any::{Any, TypeId};
 /// # }
 /// ```
 ///
+/// [`Reflectable`]: crate::Reflectable
 /// [utility]: crate::utility
 pub trait Typed: Reflect {
     /// Returns the compile-time [info] for the underlying type.
diff --git a/crates/bevy_reflect/src/type_registry.rs b/crates/bevy_reflect/src/type_registry.rs
index fe3302774b7616..513ad222770fdb 100644
--- a/crates/bevy_reflect/src/type_registry.rs
+++ b/crates/bevy_reflect/src/type_registry.rs
@@ -31,6 +31,10 @@ impl Debug for TypeRegistryArc {
 /// A trait which allows a type to generate its [`TypeRegistration`].
 ///
 /// This trait is automatically implemented for types which derive [`Reflect`].
+///
+/// As a core trait to the reflection system, it is a supertrait of [`Reflectable`].
+///
+/// [`Reflectable`]: crate::Reflectable
 pub trait GetTypeRegistration {
     fn get_type_registration() -> TypeRegistration;
 }