serializer processor doc tests

Author: aecsocket

crates/bevy_reflect/src/serde/ser/serializer.rs

@@ -14,7 +14,155 @@ use crate::{
 };
 use serde::{ser::SerializeMap, Serialize, Serializer};
 
+/// Allows overriding the default serialization behaviour of
+/// [`ReflectSerializer`] and [`TypedReflectSerializer`] for specific values.
+///
+/// When serializing a reflected value, you may want to override the default
+/// behaviour and use your own logic for serialization. This logic may also be
+/// context-dependent, and only apply for a single use of your
+/// [`ReflectSerializer`]. To achieve this, you can create a processor and pass
+/// it into your serializer.
+///
+/// Whenever the serializer attempts to serialize a value, it will first call
+/// [`try_serialize`] on your processor, which may take ownership of the
+/// serializer and write into the serializer (successfully or not), or return
+/// ownership of the serializer back, and continue with the default logic.
+///
+/// # Examples
+///
+/// Serializing a reflected value when saving an asset to disk, and replacing
+/// asset handles with the handle path (if it has one):
+///
+/// ```
+/// # use core::any::Any;
+/// # use serde::Serialize;
+/// # use bevy_reflect::{Reflect, TypeData, TypeRegistry};
+/// # use bevy_reflect::serde::{ReflectSerializer, ReflectSerializerProcessor};
+/// #
+/// # #[derive(Debug, Clone, Reflect)]
+/// # struct Handle<T>(T);
+/// # #[derive(Debug, Clone, Reflect)]
+/// # struct Mesh;
+/// #
+/// # struct ReflectHandle;
+/// # impl TypeData for ReflectHandle {
+/// #     fn clone_type_data(&self) -> Box<dyn TypeData> {
+/// #         unimplemented!()
+/// #     }
+/// # }
+/// # impl ReflectHandle {
+/// #     fn downcast_handle_untyped(&self, handle: &(dyn Any + 'static)) -> Option<UntypedHandle> {
+/// #         unimplemented!()
+/// #     }
+/// # }
+/// #
+/// # #[derive(Debug, Clone)]
+/// # struct UntypedHandle;
+/// # impl UntypedHandle {
+/// #     fn path(&self) -> Option<&str> {
+/// #         unimplemented!()
+/// #     }
+/// # }
+/// # type AssetError = Box<dyn core::error::Error>;
+/// #
+/// #[derive(Debug, Clone, Reflect)]
+/// struct MyAsset {
+///     name: String,
+///     mesh: Handle<Mesh>,
+/// }
+///
+/// struct HandleProcessor;
+///
+/// impl ReflectSerializerProcessor for HandleProcessor {
+///     fn try_serialize<S>(
+///         &self,
+///         value: &dyn crate::PartialReflect,
+///         registry: &TypeRegistry,
+///         serializer: S,
+///     ) -> Result<Result<S::Ok, S>, S::Error>
+///     where
+///         S: serde::Serializer,
+///     {
+///         let Some(value) = value.try_as_reflect() else {
+///             // we don't have any info on this type; do the default logic
+///             return Ok(Err(serializer));
+///         };
+///         let type_id = value.reflect_type_info().type_id();
+///         let Some(reflect_handle) = registry.get_type_data::<ReflectHandle>(type_id) else {
+///             // this isn't a `Handle<T>`
+///             return Ok(Err(serializer));
+///         };
+///
+///         let untyped_handle = reflect_handle
+///             .downcast_handle_untyped(value.as_any())
+///             .unwrap();
+///         if let Some(path) = untyped_handle.path() {
+///             serializer.serialize_str(path).map(Ok)
+///         } else {
+///             serializer.serialize_unit().map(Ok)
+///         }
+///     }
+/// }
+///
+/// fn save(type_registry: &TypeRegistry, asset: &MyAsset) -> Result<Vec<u8>, AssetError> {
+///     let mut asset_bytes = Vec::new();
+///
+///     let processor = HandleProcessor;
+///     let serializer = ReflectSerializer::with_processor(asset, type_registry, &processor);
+///     let ron_serializer = ron::Serializer::new(&mut asset_bytes, None);
+///
+///     serializer.serialize(serializer)?;
+///     Ok(asset_bytes)
+/// }
+/// ```
+///
+/// [`try_serialize`]: Self::try_serialize
 pub trait ReflectSerializerProcessor {
+    /// Attempts to serialize the value which a [`TypedReflectSerializer`] is
+    /// currently looking at.
+    ///
+    /// If you want to override the default deserialization, return
+    /// `Ok(Ok(value))` with an `Ok` output from the serializer.
+    ///
+    /// If you don't want to override the serialization, return ownership of
+    /// the serializer back via `Ok(Err(serializer))`.
+    ///
+    /// To get useful info about the type of value you're serializing, you will
+    /// likely want to convert it to a [`Reflect`] and read its type info from
+    /// the given registry:
+    ///
+    /// ```
+    /// # use bevy_reflect::{TypeRegistration, TypeRegistry, PartialReflect};
+    /// # use bevy_reflect::serde::ReflectDeserializerProcessor;
+    /// # use core::any::TypeId;
+    /// struct I32AsStringProcessor;
+    ///
+    /// impl ReflectSerializerProcessor for I32AsStringProcessor {
+    ///     fn try_serialize<S>(
+    ///         &self,
+    ///         value: &dyn PartialReflect,
+    ///         registry: &TypeRegistry,
+    ///         serializer: S,
+    ///     ) -> Result<Result<S::Ok, S>, S::Error>
+    ///     where
+    ///         S: serde::Serializer
+    ///     {
+    ///         let Some(value) = value.try_as_reflect() else {
+    ///             // this value isn't `Reflect`, just do the default serialization
+    ///             return Ok(Err(serializer));
+    ///         };
+    ///         // actually read the type ID of this value
+    ///         let type_id = value.reflect_type_info().type_id();
+    ///
+    ///         if type_id == TypeId::of::<i32>() {
+    ///             let value_as_string = format!("{value:?}");
+    ///             serializer.serialize_str(value_as_string).map(Ok)
+    ///         } else {
+    ///             Ok(Err(serializer))
+    ///         }
+    ///     }
+    /// }
+    /// ```
     fn try_serialize<S>(
         &self,
         value: &dyn PartialReflect,
@@ -51,6 +199,10 @@ impl ReflectSerializerProcessor for () {
 /// where the key is the _full_ [type path] of the reflected type
 /// and the value is the serialized data.
 ///
+/// If you want to override serialization for specific values, you can pass in
+/// a reference to a [`ReflectSerializerProcessor`] which will take priority
+/// over all other serialization methods - see [`with_processor`].
+///
 /// # Example
 ///
 /// ```
@@ -75,13 +227,20 @@ impl ReflectSerializerProcessor for () {
 ///
 /// [`ReflectDeserializer`]: crate::serde::ReflectDeserializer
 /// [type path]: crate::TypePath::type_path
+/// [`with_processor`]: Self::with_processor
 pub struct ReflectSerializer<'a, P = ()> {
     value: &'a dyn PartialReflect,
     registry: &'a TypeRegistry,
     processor: Option<&'a P>,
 }
 
 impl<'a> ReflectSerializer<'a, ()> {
+    /// Creates a serializer with no processor.
+    ///
+    /// If you want to add custom logic for serializing certain values, use
+    /// [`with_processor`].
+    ///
+    /// [`with_processor`]: Self::with_processor
     pub fn new(value: &'a dyn PartialReflect, registry: &'a TypeRegistry) -> Self {
         Self {
             value,
@@ -92,6 +251,12 @@ impl<'a> ReflectSerializer<'a, ()> {
 }
 
 impl<'a, P: ReflectSerializerProcessor> ReflectSerializer<'a, P> {
+    /// Creates a serializer with a processor.
+    ///
+    /// If you do not need any custom logic for handling certain values, use
+    /// [`new`].
+    ///
+    /// [`new`]: Self::new
     pub fn with_processor(
         value: &'a dyn PartialReflect,
         registry: &'a TypeRegistry,
@@ -148,6 +313,10 @@ impl<P: ReflectSerializerProcessor> Serialize for ReflectSerializer<'_, P> {
 ///
 /// Instead, it will output just the serialized data.
 ///
+/// If you want to override serialization for specific values, you can pass in
+/// a reference to a [`ReflectSerializerProcessor`] which will take priority
+/// over all other serialization methods - see [`with_processor`].
+///
 /// # Example
 ///
 /// ```
@@ -172,13 +341,20 @@ impl<P: ReflectSerializerProcessor> Serialize for ReflectSerializer<'_, P> {
 ///
 /// [`TypedReflectDeserializer`]: crate::serde::TypedReflectDeserializer
 /// [type path]: crate::TypePath::type_path
+/// [`with_processor`]: Self::with_processor
 pub struct TypedReflectSerializer<'a, P = ()> {
     value: &'a dyn PartialReflect,
     registry: &'a TypeRegistry,
     processor: Option<&'a P>,
 }
 
 impl<'a> TypedReflectSerializer<'a, ()> {
+    /// Creates a serializer with no processor.
+    ///
+    /// If you want to add custom logic for serializing certain values, use
+    /// [`with_processor`].
+    ///
+    /// [`with_processor`]: Self::with_processor
     pub fn new(value: &'a dyn PartialReflect, registry: &'a TypeRegistry) -> Self {
         #[cfg(feature = "debug_stack")]
         TYPE_INFO_STACK.set(crate::type_info_stack::TypeInfoStack::new());
@@ -192,6 +368,12 @@ impl<'a> TypedReflectSerializer<'a, ()> {
 }
 
 impl<'a, P> TypedReflectSerializer<'a, P> {
+    /// Creates a serializer with a processor.
+    ///
+    /// If you do not need any custom logic for handling certain values, use
+    /// [`new`].
+    ///
+    /// [`new`]: Self::new
     pub fn with_processor(
         value: &'a dyn PartialReflect,
         registry: &'a TypeRegistry,