Updated documentation

Author: MrGVSV

crates/bevy_reflect/src/serde/deserialize_reflect.rs

@@ -13,10 +13,18 @@ use serde::{Deserialize, Deserializer};
 /// want to handle parts of the deserialization process, but temporarily pass control
 /// to the standard reflection deserializer for other parts.
 ///
+/// For the serializtion equivalent of this trait, see [`SerializeReflect`].
+///
+/// # Rationale
+///
 /// Without this trait and its associated [type data], such a deserializer would have to
 /// write out all of the deserialization logic itself, possibly including
 /// unnecessary code duplication and trivial implementations.
 ///
+/// This is because a normal [`Deserialize`] implementation has no knowledge of the
+/// [`TypeRegistry`] and therefore cannot create a reflection-based deserializer for
+/// nested items.
+///
 /// # Implementors
 ///
 /// In order for this to work with the reflection deserializers like [`TypedReflectDeserializer`]
@@ -26,8 +34,9 @@ use serde::{Deserialize, Deserializer};
 /// the type definition.
 ///
 /// Note that this trait has a blanket implementation for all types that implement
-/// [`Reflect`] and [`Deserialize`].
+/// [`Reflect`] and [`Deserialize`] which just calls the normal [`Deserialize`] implementation.
 ///
+/// [`SerializeReflect`]: crate::serde::SerializeReflect
 /// [type data]: ReflectDeserializeReflect
 /// [`TypedReflectDeserializer`]: crate::serde::TypedReflectDeserializer
 /// [`UntypedReflectDeserializer`]: crate::serde::UntypedReflectDeserializer

crates/bevy_reflect/src/serde/serialize_reflect.rs

@@ -13,11 +13,17 @@ use serde::{Serialize, Serializer};
 /// want to handle parts of the serialization process, but temporarily pass control
 /// to the standard reflection serializer for other parts.
 ///
+/// For the deserializtion equivalent of this trait, see [`DeserializeReflect`].
+///
+/// # Rationale
+///
 /// Without this trait and its associated [type data], such a serializer would have to
 /// write out all of the serialization logic itself, possibly including
 /// unnecessary code duplication and trivial implementations.
 ///
-/// For the deserializtion equivalent of this trait, see [`DeserializeReflect`].
+/// This is because a normal [`Serialize`] implementation has no knowledge of the
+/// [`TypeRegistry`] and therefore cannot create a reflection-based serializer for
+/// nested items.
 ///
 /// # Implementors
 ///
@@ -28,8 +34,9 @@ use serde::{Serialize, Serializer};
 /// the type definition.
 ///
 /// Note that this trait has a blanket implementation for all types that implement
-/// [`Reflect`] and [`Serialize`].
+/// [`Reflect`] and [`Serialize`] which just calls the normal [`Serialize`] implementation.
 ///
+/// [`DeserializeReflect`]: crate::serde::DeserializeReflect
 /// [type data]: ReflectSerializeReflect
 /// [`TypedReflectSerializer`]: crate::serde::TypedReflectSerializer
 /// [`ReflectSerializer`]: crate::serde::ReflectSerializer