Update docs

crates/bevy_reflect/src/diff/mod.rs

@@ -17,6 +17,28 @@
 //! When a value is [modified], it contains data related to the modification,
 //! which may recursively contain more [`Diff`] objects.
 //!
+//! # Applying Diffs
+//!
+//! Diffs store the changes between two values, but they also allow for these changes to be applied to a value.
+//!
+//! To apply a diff, you can use either the [`Reflect::apply_diff`] method or the [`Diff::apply`] method.
+//!
+//! Note that diff's hold on to references to both the "old" and "new" values.
+//! This means you won't be able to apply a diff to the "old" value unless you clone the diff
+//! with [`Diff::clone_diff`] first.
+//!
+//! ```
+//! # use bevy_reflect::Reflect;
+//! let old = (1, 2, 3);
+//! let new = (0, 2, 4);
+//!
+//! let diff = old.diff(&new).unwrap();
+//!
+//! let mut value = (1, 2, 3);
+//! diff.apply(&mut value).unwrap();
+//! assert_eq!(value, new);
+//! ```
+//!
 //! # Lists & Maps
 //!
 //! It's important to note that both [List](crate::List) and [Map](crate::Map) types work a bit differently
@@ -109,6 +131,7 @@
 //! [modified]: Diff::Modified
 //! [replaced]: Diff::Replaced
 //! [no change]: Diff::NoChange
+//! [`Reflect::apply_diff`]: crate::Reflect::apply_diff
 //! [Myers Diffing Algorithm]: http://www.xmailserver.org/diff2.pdf
 
 mod array_diff;

crates/bevy_reflect/src/type_info.rs

@@ -26,6 +26,7 @@ use std::fmt::Debug;
 /// ```
 /// # use std::any::Any;
 /// # use bevy_reflect::{DynamicTypePath, NamedField, Reflect, ReflectMut, ReflectOwned, ReflectRef, StructInfo, TypeInfo, TypePath, ValueInfo, ApplyError};
+/// # use bevy_reflect::diff::DiffResult;
 /// # use bevy_reflect::utility::NonGenericTypeInfoCell;
 /// use bevy_reflect::Typed;
 ///
@@ -66,6 +67,7 @@ use std::fmt::Debug;
 /// #   fn reflect_mut(&mut self) -> ReflectMut { todo!() }
 /// #   fn reflect_owned(self: Box<Self>) -> ReflectOwned { todo!() }
 /// #   fn clone_value(&self) -> Box<dyn Reflect> { todo!() }
+/// #   fn diff<'new>(&self, other: &'new dyn Reflect) -> DiffResult<'_, 'new> { todo!() }
 /// # }
 /// ```
 ///

crates/bevy_reflect/src/utility.rs

@@ -50,6 +50,7 @@ mod sealed {
 /// ```
 /// # use std::any::Any;
 /// # use bevy_reflect::{DynamicTypePath, NamedField, Reflect, ReflectMut, ReflectOwned, ReflectRef, StructInfo, Typed, TypeInfo, TypePath, ApplyError};
+/// # use bevy_reflect::diff::DiffResult;
 /// use bevy_reflect::utility::NonGenericTypeInfoCell;
 ///
 /// struct Foo {
@@ -84,6 +85,7 @@ mod sealed {
 /// #     fn reflect_mut(&mut self) -> ReflectMut { todo!() }
 /// #     fn reflect_owned(self: Box<Self>) -> ReflectOwned { todo!() }
 /// #     fn clone_value(&self) -> Box<dyn Reflect> { todo!() }
+/// #     fn diff<'new>(&self, other: &'new dyn Reflect) -> DiffResult<'_, 'new> { todo!() }
 /// # }
 /// ```
 ///
@@ -131,6 +133,7 @@ impl<T: TypedProperty> Default for NonGenericTypeCell<T> {
 /// ```
 /// # use std::any::Any;
 /// # use bevy_reflect::{DynamicTypePath, Reflect, ReflectMut, ReflectOwned, ReflectRef, TupleStructInfo, Typed, TypeInfo, TypePath, UnnamedField, ApplyError};
+/// # use bevy_reflect::diff::DiffResult;
 /// use bevy_reflect::utility::GenericTypeInfoCell;
 ///
 /// struct Foo<T>(T);
@@ -163,6 +166,7 @@ impl<T: TypedProperty> Default for NonGenericTypeCell<T> {
 /// #     fn reflect_mut(&mut self) -> ReflectMut { todo!() }
 /// #     fn reflect_owned(self: Box<Self>) -> ReflectOwned { todo!() }
 /// #     fn clone_value(&self) -> Box<dyn Reflect> { todo!() }
+/// #     fn diff<'new>(&self, other: &'new dyn Reflect) -> DiffResult<'_, 'new> { todo!() }
 /// # }
 /// ```
 ///