From 4c22c87b48f5a2f1ec44c5fa15bd8d16d5cd301f Mon Sep 17 00:00:00 2001
From: Gino Valente <gino.valente.code@gmail.com>
Date: Mon, 25 Mar 2024 17:34:52 -0700
Subject: [PATCH] Update serializer documentation

---
 crates/bevy_reflect/src/serde/ser.rs | 75 ++++++++++++++++++++++++++--
 1 file changed, 70 insertions(+), 5 deletions(-)

diff --git a/crates/bevy_reflect/src/serde/ser.rs b/crates/bevy_reflect/src/serde/ser.rs
index c67b81e8cc2e2e..08e124945cbb63 100644
--- a/crates/bevy_reflect/src/serde/ser.rs
+++ b/crates/bevy_reflect/src/serde/ser.rs
@@ -52,10 +52,39 @@ fn get_serializable<'a, E: Error>(
 
 /// A general purpose serializer for reflected types.
 ///
-/// The serialized data will take the form of a map containing the following entries:
-/// 1. `type`: The _full_ [type path]
-/// 2. `value`: The serialized value of the reflected type
+/// This is the serializer counterpart to [`ReflectDeserializer`].
 ///
+/// See [`TypedReflectSerializer`] for a serializer that serializes a known type.
+///
+/// # Output
+///
+/// This serializer will output a map with a single entry,
+/// where the key is the _full_ [type path] of the reflected type
+/// and the value is the serialized data.
+///
+/// # Example
+///
+/// ```
+/// # use bevy_reflect::prelude::*;
+/// # use bevy_reflect::{TypeRegistry, serde::ReflectSerializer};
+/// #[derive(Reflect, PartialEq, Debug)]
+/// #[type_path = "my_crate"]
+/// struct MyStruct {
+///   value: i32
+/// }
+///
+/// let mut registry = TypeRegistry::default();
+/// registry.register::<MyStruct>();
+///
+/// let input = MyStruct { value: 123 };
+///
+/// let reflect_serializer = ReflectSerializer::new(&input, &registry);
+/// let output = ron::to_string(&reflect_serializer).unwrap();
+///
+/// assert_eq!(output, r#"{"my_crate::MyStruct":(value:123)}"#);
+/// ```
+///
+/// [`ReflectDeserializer`]: crate::serde::ReflectDeserializer
 /// [type path]: crate::TypePath::type_path
 pub struct ReflectSerializer<'a> {
     pub value: &'a dyn Reflect,
@@ -97,8 +126,44 @@ impl<'a> Serialize for ReflectSerializer<'a> {
     }
 }
 
-/// A serializer for reflected types whose type is known and does not require
-/// serialization to include other metadata about it.
+/// A serializer for reflected types whose type will be known during deserialization.
+///
+/// This is the serializer counterpart to [`TypedReflectDeserializer`].
+///
+/// See [`ReflectSerializer`] for a serializer that serializes an unknown type.
+///
+/// # Output
+///
+/// Since the type is expected to be known during deserialization,
+/// this serializer will not output any additional type information,
+/// such as the [type path].
+///
+/// Instead, it will output just the serialized data.
+///
+/// # Example
+///
+/// ```
+/// # use bevy_reflect::prelude::*;
+/// # use bevy_reflect::{TypeRegistry, serde::TypedReflectSerializer};
+/// #[derive(Reflect, PartialEq, Debug)]
+/// #[type_path = "my_crate"]
+/// struct MyStruct {
+///   value: i32
+/// }
+///
+/// let mut registry = TypeRegistry::default();
+/// registry.register::<MyStruct>();
+///
+/// let input = MyStruct { value: 123 };
+///
+/// let reflect_serializer = TypedReflectSerializer::new(&input, &registry);
+/// let output = ron::to_string(&reflect_serializer).unwrap();
+///
+/// assert_eq!(output, r#"(value:123)"#);
+/// ```
+///
+/// [`TypedReflectDeserializer`]: crate::serde::TypedReflectDeserializer
+/// [type path]: crate::TypePath::type_path
 pub struct TypedReflectSerializer<'a> {
     pub value: &'a dyn Reflect,
     pub registry: &'a TypeRegistry,