Document type registration items

Author: MrGVSV

crates/bevy_reflect/src/type_registry.rs

@@ -40,9 +40,16 @@ impl Debug for TypeRegistryArc {
     }
 }
 
-/// A trait which allows a type to generate its [`TypeRegistration`].
+/// A trait which allows a type to generate its [`TypeRegistration`]
+/// for registration into the [`TypeRegistry`].
 ///
-/// This trait is automatically implemented for types which derive [`Reflect`].
+/// This trait is automatically implemented for items using the [`Reflect` derive macro].
+/// The macro also allows [`TypeData`] to be more easily registered.
+///
+/// See the [crate-level documentation] for more information on type registration.
+///
+/// [`Reflect` derive macro]: bevy_reflect_derive::Reflect
+/// [crate-level documentation]: crate
 pub trait GetTypeRegistration {
     fn get_type_registration() -> TypeRegistration;
 }
@@ -269,19 +276,33 @@ impl TypeRegistryArc {
     }
 }
 
-/// A record of data about a type.
+/// Runtime storage for type metadata, registered into the [`TypeRegistry`].
+///
+/// An instance of `TypeRegistration` can be created using the [`TypeRegistration::of`] method,
+/// but is more often automatically generated using the [`Reflect` derive macro] which itself generates
+/// an implementation of the [`GetTypeRegistration`] trait.
 ///
-/// This contains the [`TypeInfo`] of the type, as well as its [short name].
+/// Along with the type's [`TypeInfo`] and [short name],
+/// this struct also contains a type's registered [`TypeData`].
+///
+/// See the [crate-level documentation] for more information on type registration.
+///
+/// # Example
+///
+/// ```
+/// # use bevy_reflect::{TypeRegistration, std_traits::ReflectDefault, FromType};
+/// let mut registration = TypeRegistration::of::<Option<String>>();
 ///
-/// For each trait specified by the [`#[reflect(_)]`][0] attribute of
-/// [`#[derive(Reflect)]`][1] on the registered type, this record also contains
-/// a [`TypeData`] which can be used to downcast [`Reflect`] trait objects of
-/// this type to trait objects of the relevant trait.
+/// assert_eq!("core::option::Option<alloc::string::String>", registration.type_name());
+/// assert_eq!("Option<String>", registration.short_name());
 ///
+/// registration.insert::<ReflectDefault>(FromType::<Option<String>>::from_type());
+/// assert!(registration.data::<ReflectDefault>().is_some())
+/// ```
+///
+/// [`Reflect` derive macro]: bevy_reflect_derive::Reflect
 /// [short name]: bevy_utils::get_short_name
-/// [`TypeInfo`]: crate::TypeInfo
-/// [0]: crate::Reflect
-/// [1]: crate::Reflect
+/// [crate-level documentation]: crate
 pub struct TypeRegistration {
     short_name: String,
     data: HashMap<TypeId, Box<dyn TypeData>>,
@@ -377,9 +398,19 @@ impl Clone for TypeRegistration {
         }
     }
 }
-/// A trait for types generated by the [`#[reflect_trait]`][0] attribute macro.
+
+/// A trait used to type-erase type metadata.
+///
+/// Type data can be registered to the [`TypeRegistry`] and stored on a type's [`TypeRegistration`].
+///
+/// While type data is often generated using the [`#[reflect_trait]`][0] macro,
+/// almost any type that implements [`Clone`] can be considered "type data".
+/// This is because it has a blanket implementation over all `T` where `T: Clone + Send + Sync + 'static`.
+///
+/// See the [crate-level documentation] for more information on type data and type registration.
 ///
 /// [0]: crate::reflect_trait
+/// [crate-level documentation]: crate
 pub trait TypeData: Downcast + Send + Sync {
     fn clone_type_data(&self) -> Box<dyn TypeData>;
 }