[Merged by Bors] - bevy_reflect: Improved documentation

crates/bevy_reflect/bevy_reflect_derive/src/lib.rs

@@ -41,7 +41,89 @@ use type_uuid::TypeUuidDef;
 pub(crate) static REFLECT_ATTRIBUTE_NAME: &str = "reflect";
 pub(crate) static REFLECT_VALUE_ATTRIBUTE_NAME: &str = "reflect_value";
 
-#[proc_macro_derive(Reflect, attributes(reflect, reflect_value, module))]
+/// The main derive macro used by `bevy_reflect` for deriving its `Reflect` trait.
+///
+/// This macro can be used on all structs and enums (unions are not supported).
+/// It will automatically generate the implementations for `Reflect`, `Typed`, and `GetTypeRegistration`.
+/// And, depending on the item's structure, will either implement `Struct`, `TupleStruct`, or `Enum`.
+///
+/// # Container Attributes
+///
+/// This macro comes with some helper attributes that can be added to the container item
+/// in order to provide additional functionality or alter the generated implementations.
+///
+/// ## `#[reflect(Ident)]`
+///
+/// The `#[reflect(Ident)]` attribute is used to add type data registrations to the `GetTypeRegistration`
+/// implementation corresponding to the given identifier, prepended by `Reflect`.
+///
+/// For example, `#[reflect(Foo, Bar)]` would add two registrations:
+/// one for `ReflectFoo` and another for `ReflectBar`.
+/// This assumes these types are indeed in-scope wherever this macro is called.
+///
+/// This is often used with traits that have been marked by the [`#[reflect_trait]`](macro@reflect_trait)
+/// macro in order to register the type's implementation of that trait.
+///
+/// ### Special Identifiers
+///
+/// There are a few "special" identifiers that work a bit differently:
+///
+/// * `#[reflect(Debug)]` will force the implementation of `Reflect::reflect_debug` to rely on
+///   the type's [`Debug`] implementation.
+///   A custom implementation may be provided using `#[reflect(Debug(my_debug_func))]` where
+///   `my_debug_func` is the path to a function matching the signature:
+///   `(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result`.
+/// * `#[reflect(PartialEq)]` will force the implementation of `Reflect::reflect_partial_eq` to rely on
+///   the type's [`PartialEq`] implementation.
+///   A custom implementation may be provided using `#[reflect(PartialEq(my_partial_eq_func))]` where
+///   `my_partial_eq_func` is the path to a function matching the signature:
+///   `(&self, value: &dyn #bevy_reflect_path::Reflect) -> bool`.
+/// * `#[reflect(Hash)]` will force the implementation of `Reflect::reflect_hash` to rely on
+///   the type's [`Hash`] implementation.
+///   A custom implementation may be provided using `#[reflect(Hash(my_hash_func))]` where
+///   `my_hash_func` is the path to a function matching the signature: `(&self) -> u64`.
+/// * `#[reflect(Default)]` will register the `ReflectDefault` type data as normal.
+///   However, it will also affect how certain other operations are performed in order
+///   to improve performance and/or robustness.
+///   An example of where this is used is in the [`FromReflect`] derive macro,
+///   where adding this attribute will cause the `FromReflect` implementation to create
+///   a base value using its [`Default`] implementation avoiding issues with ignored fields.
+///
+/// ## `#[reflect_value]`
+///
+/// The `#[reflect_value]` attribute (which may also take the form `#[reflect_value(Ident)]`),
+/// denotes that the item should implement `Reflect` as though it were a base value type.
+/// This means that it will forgo implementing `Struct`, `TupleStruct`, or `Enum`.
+///
+/// Furthermore, it requires that the type implements [`Clone`].
+/// If planning to serialize this type using the reflection serializers,
+/// then the `Serialize` and `Deserialize` traits will need to be implemented and registered as well.
+///
+/// # Field Attributes
+///
+/// Along with the container attributes, this macro comes with some attributes that may be applied
+/// to the contained fields themselves.
+///
+/// ## `#[reflect(ignore)]`
+///
+/// This attribute simply marks a field to be ignored by the reflection API.
+///
+/// This allows fields to completely opt-out of reflection,
+/// which may be useful for maintaining invariants, keeping certain data private,
+/// or allowing the use of types that do not implement `Reflect` within the container.
+///
+/// ## `#[reflect(skip_serializing)]`
+///
+/// This works similar to `#[reflect(ignore)]`, but rather than opting out of _all_ of reflection,
+/// it simply opts the field out of both serialization and deserialization.
+/// This can be useful when a field should be accessible via reflection, but may not make
+/// sense in a serialized form, such as computed data.
+///
+/// What this does is register the `SerializationData` type within the `GetTypeRegistration` implementation,
+/// which will be used by the reflection serializers to determine whether or not the field is serializable.
+///
+/// [`reflect_trait`]: macro@reflect_trait
+#[proc_macro_derive(Reflect, attributes(reflect, reflect_value))]
 pub fn derive_reflect(input: TokenStream) -> TokenStream {
     let ast = parse_macro_input!(input as DeriveInput);
 
@@ -62,11 +144,30 @@ pub fn derive_reflect(input: TokenStream) -> TokenStream {
 
 /// Derives the `FromReflect` trait.
 ///
-/// This macro supports the following field attributes:
-/// * `#[reflect(ignore)]`: Ignores the field. This requires the field to implement [`Default`].
-/// * `#[reflect(default)]`: If the field's value cannot be read, uses its [`Default`] implementation.
-/// * `#[reflect(default = "some_func")]`: If the field's value cannot be read, uses the function with the given name.
+/// # Field Attributes
+///
+/// ## `#[reflect(ignore)]`
 ///
+/// The `#[reflect(ignore)]` attribute is shared with the [`#[derive(Reflect)]`](Reflect) macro and has much of the same
+/// functionality in that it denotes that a field will be ignored by the reflection API.
+///
+/// The only major difference is that using it with this derive requires that the field implements [`Default`].
+/// Without this requirement, there would be no way for `FromReflect` to automatically construct missing fields
+/// that have been ignored.
+///
+/// ## `#[reflect(default)]`
+///
+/// If a field cannot be read, this attribute specifies a default value to be used in its place.
+///
+/// By default, this attribute denotes that the field's type implements [`Default`].
+/// However, it can also take in a path string to a user-defined function that will return the default value.
+/// This takes the form: `#[reflect(default = "path::to::my_function)]` where `my_function` is a parameterless
+/// function that must return some default value for the type.
+///
+/// Specifying a custom default can be used to give different fields their own specialized defaults,
+/// or to remove the `Default` requirement on fields marked with `#[reflect(ignore)]`.
+/// Additionally, either form of this attribute can be used to fill in fields that are simply missing,
+/// such as when converting a partially-constructed dynamic type to a concrete one.
 #[proc_macro_derive(FromReflect, attributes(reflect))]
 pub fn derive_from_reflect(input: TokenStream) -> TokenStream {
     let ast = parse_macro_input!(input as DeriveInput);
@@ -92,11 +193,82 @@ pub fn derive_type_uuid(input: TokenStream) -> TokenStream {
     type_uuid::type_uuid_derive(input)
 }
 
+/// A macro that automatically generates type data for traits, which their implementors can then register.
+///
+/// The output of this macro is a struct that takes reflected instances of the implementor's type
+/// and returns the value as a trait object.
+/// Because of this, **it can only be used on [object-safe] traits.**
+///
+/// For a trait named `MyTrait`, this will generate the struct `ReflectMyTrait`.
+/// The generated struct can be created using `FromType` with any type that implements the trait.
+/// The creation and registration of this generated struct as type data can be automatically handled
+/// by [`#[derive(Reflect)]`](Reflect).
+///
+/// # Example
+///
+/// ```ignore
+/// # use std::any::TypeId;
+/// # use bevy_reflect_derive::{Reflect, reflect_trait};
+/// #[reflect_trait] // Generates `ReflectMyTrait`
+/// trait MyTrait {
+///   fn print(&self) -> &str;
+/// }
+///
+/// #[derive(Reflect)]
+/// #[reflect(MyTrait)] // Automatically registers `ReflectMyTrait`
+/// struct SomeStruct;
+///
+/// impl MyTrait for SomeStruct {
+///   fn print(&self) -> &str {
+///     "Hello, World!"
+///   }
+/// }
+///
+/// // We can create the type data manually if we wanted:
+/// let my_trait: ReflectMyTrait = FromType::<SomeStruct>::from_type();
+///
+/// // Or we can simply get it from the registry:
+/// let mut registry = TypeRegistry::default();
+/// registry.register::<SomeStruct>();
+/// let my_trait = registry
+///   .get_type_data::<ReflectMyTrait>(TypeId::of::<SomeStruct>())
+///   .unwrap();
+///
+/// // Then use it on reflected data
+/// let reflected: Box<dyn Reflect> = Box::new(SomeStruct);
+/// let reflected_my_trait: &dyn MyTrait = my_trait.get(&*reflected).unwrap();
+/// assert_eq!("Hello, World!", reflected_my_trait.print());
+/// ```
+///
+/// [object-safe]: https://doc.rust-lang.org/reference/items/traits.html#object-safety
 #[proc_macro_attribute]
 pub fn reflect_trait(args: TokenStream, input: TokenStream) -> TokenStream {
     trait_reflection::reflect_trait(&args, input)
 }
 
+/// A macro used to generate reflection trait implementations for the given type.
+///
+/// This is functionally the same as [deriving `Reflect`] using the `#[reflect_value]` container attribute.
+///
+/// The only reason for this macro's existence is so that `bevy_reflect` can easily implement the reflection traits
+/// on primitives and other Rust types internally.
+///
+/// # Examples
+///
+/// Types can be passed with or without registering type data:
+///
+/// ```ignore
+/// impl_reflect_value!(foo);
+/// impl_reflect_value!(bar(Debug, Default, Serialize, Deserialize));
+/// ```
+///
+/// Generic types can also specify their parameters and bounds:
+///
+/// ```ignore
+/// impl_reflect_value!(foo<T1, T2: Baz> where T1: Bar (Default, Serialize, Deserialize));
+/// ```
+///
+/// [deriving `Reflect`]: Reflect
 #[proc_macro]
 pub fn impl_reflect_value(input: TokenStream) -> TokenStream {
     let def = parse_macro_input!(input as ReflectValueDef);
@@ -178,6 +350,22 @@ pub fn impl_reflect_struct(input: TokenStream) -> TokenStream {
     }
 }
 
+/// A macro used to generate a `FromReflect` trait implementation for the given type.
+///
+/// This is functionally the same as [deriving `FromReflect`] on a type that [derives `Reflect`] using
+/// the `#[reflect_value]` container attribute.
+///
+/// The only reason this macro exists is so that `bevy_reflect` can easily implement `FromReflect` on
+/// primitives and other Rust types internally.
+///
+/// # Examples
+///
+/// ```ignore
+/// impl_from_reflect_value!(foo<T1, T2: Baz> where T1: Bar);
+/// ```
+///
+/// [deriving `FromReflect`]: FromReflect
+/// [derives `Reflect`]: Reflect
 #[proc_macro]
 pub fn impl_from_reflect_value(input: TokenStream) -> TokenStream {
     let def = parse_macro_input!(input as ReflectValueDef);

crates/bevy_reflect/src/array.rs

@@ -8,16 +8,41 @@ use std::{
     hash::{Hash, Hasher},
 };
 
-/// A static-sized array of [`Reflect`] items.
+/// A trait used to power [array-like] operations via [reflection].
 ///
-/// This corresponds to types like `[T; N]` (arrays).
+/// This corresponds to true Rust arrays like `[T; N]`,
+/// but also to any fixed-size linear sequence types.
+/// It is expected that implementors of this trait uphold this contract
+/// and maintain a fixed size as returned by the [`Array::len`] method.
 ///
-/// Currently, this only supports arrays of up to 32 items. It can technically
-/// contain more than 32, but the blanket [`GetTypeRegistration`] is only
-/// implemented up to the 32 item limit due to a [limitation] on `Deserialize`.
+/// Due to the [type-erasing] nature of the reflection API as a whole,
+/// this trait does not make any guarantees that the implementor's elements
+/// are homogenous (i.e. all the same type).
 ///
+/// This trait has a blanket implementation over Rust arrays of up to 32 items.
+/// This implementation can technically contain more than 32,
+/// but the blanket [`GetTypeRegistration`] is only implemented up to the 32
+/// item limit due to a [limitation] on [`Deserialize`].
+///
+/// # Example
+///
+/// ```
+/// use bevy_reflect::{Reflect, Array};
+///
+/// let foo: &dyn Array = &[123_u32, 456_u32, 789_u32];
+/// assert_eq!(foo.len(), 3);
+///
+/// let field: &dyn Reflect = foo.get(0).unwrap();
+/// assert_eq!(field.downcast_ref::<u32>(), Some(&123));
+/// ```
+///
+/// [array-like]: https://doc.rust-lang.org/book/ch03-02-data-types.html#the-array-type
+/// [reflection]: crate
+/// [`List`]: crate::List
+/// [type-erasing]: https://doc.rust-lang.org/book/ch17-02-trait-objects.html
 /// [`GetTypeRegistration`]: crate::GetTypeRegistration
 /// [limitation]: https://github.com/serde-rs/serde/issues/1937
+/// [`Deserialize`]: ::serde::Deserialize
 pub trait Array: Reflect {
     /// Returns a reference to the element at `index`, or `None` if out of bounds.
     fn get(&self, index: usize) -> Option<&dyn Reflect>;

crates/bevy_reflect/src/enums/enum_trait.rs

@@ -3,7 +3,7 @@ use bevy_utils::HashMap;
 use std::any::{Any, TypeId};
 use std::slice::Iter;
 
-/// A trait representing a [reflected] enum.
+/// A trait used to power [enum-like] operations via [reflection].
 ///
 /// This allows enums to be processed and modified dynamically at runtime without
 /// necessarily knowing the actual type.
@@ -39,7 +39,7 @@ use std::slice::Iter;
 ///
 /// # Implementation
 ///
-/// > 💡 This trait can be automatically implemented using the [`Reflect`] derive macro
+/// > 💡 This trait can be automatically implemented using [`#[derive(Reflect)]`](derive@crate::Reflect)
 /// > on an enum definition.
 ///
 /// Despite the fact that enums can represent multiple states, traits only exist in one state
@@ -52,7 +52,7 @@ use std::slice::Iter;
 /// accessing fields!
 /// Again, this is to account for _all three_ variant types.
 ///
-/// We recommend using the built-in [`Reflect`] derive macro to automatically handle all the
+/// We recommend using the built-in [`#[derive(Reflect)]`](derive@crate::Reflect) macro to automatically handle all the
 /// implementation details for you.
 /// However, if you _must_ implement this trait manually, there are a few things to keep in mind...
 ///
@@ -82,7 +82,8 @@ use std::slice::Iter;
 /// It's preferred that these strings be converted to their proper `usize` representations and
 /// the [`Enum::field_at[_mut]`](Enum::field_at) methods be used instead.
 ///
-/// [reflected]: crate
+/// [enum-like]: https://doc.rust-lang.org/book/ch06-01-defining-an-enum.html
+/// [reflection]: crate
 /// [`None`]: core::option::Option<T>::None
 /// [`Some`]: core::option::Option<T>::Some
 /// [`Reflect`]: bevy_reflect_derive::Reflect

crates/bevy_reflect/src/from_reflect.rs

@@ -1,15 +1,26 @@
 use crate::{FromType, Reflect};
 
-/// A trait for types which can be constructed from a reflected type.
+/// A trait that enables types to be dynamically constructed from reflected data.
 ///
-/// This trait can be derived on types which implement [`Reflect`]. Some complex
-/// types (such as `Vec<T>`) may only be reflected if their element types
+/// It's recommended to use the [derive macro] rather than manually implementing this trait.
+///
+/// `FromReflect` allows dynamic proxy types, like [`DynamicStruct`], to be used to generate
+/// their concrete counterparts.
+/// It can also be used to partially or fully clone a type (depending on whether it has
+/// ignored fields or not).
+///
+/// In some cases, this trait may even be required.
+/// Deriving [`Reflect`] on an enum requires all its fields to implement `FromReflect`.
+/// Additionally, some complex types like `Vec<T>` require that their element types
 /// implement this trait.
+/// The reason for such requirements is that some operations require new data to be constructed,
+/// such as swapping to a new variant or pushing data to a homogenous list.
 ///
-/// For structs and tuple structs, fields marked with the `#[reflect(ignore)]`
-/// attribute will be constructed using the `Default` implementation of the
-/// field type, rather than the corresponding field value (if any) of the
-/// reflected value.
+/// See the [crate-level documentation] to see how this trait can be used.
+///
+/// [derive macro]: bevy_reflect_derive::FromReflect
+/// [`DynamicStruct`]: crate::DynamicStruct
+/// [crate-level documentation]: crate
 pub trait FromReflect: Reflect + Sized {
     /// Constructs a concrete instance of `Self` from a reflected value.
     fn from_reflect(reflect: &dyn Reflect) -> Option<Self>;