Doc - Improve Local SystemParam text, examples

Author: isHavvy

crates/bevy_ecs/src/system/system_param.rs

@@ -974,6 +974,10 @@ unsafe impl<'w> SystemParam for DeferredWorld<'w> {
 
 /// A system local [`SystemParam`].
 ///
+/// A system with a `Local<T>` parameter is given a private value of `T` that persists across system calls.
+///
+/// The initial value is created by calling `T`'s [`FromWorld::from_world`] (or [`Default::default`] if `T: Default`).
+///
 /// A local may only be accessed by the system itself and is therefore not visible to other systems.
 /// If two or more systems specify the same local type each will have their own unique local.
 /// If multiple [`SystemParam`]s within the same system each specify the same local type
@@ -986,29 +990,25 @@ unsafe impl<'w> SystemParam for DeferredWorld<'w> {
 /// ```
 /// # use bevy_ecs::prelude::*;
 /// # let world = &mut World::default();
-/// fn write_to_local(mut local: Local<usize>) {
-///     *local = 42;
-/// }
-/// fn read_from_local(local: Local<usize>) -> usize {
-///     *local
+/// fn counter(mut count: Local<u32>) -> u32 {
+///     *count += 1;
+///     *count
 /// }
-/// let mut write_system = IntoSystem::into_system(write_to_local);
-/// let mut read_system = IntoSystem::into_system(read_from_local);
-/// write_system.initialize(world);
-/// read_system.initialize(world);
+/// let mut counter_system = IntoSystem::into_system(counter);
+/// counter_system.initialize(world);
 ///
-/// assert_eq!(read_system.run((), world).unwrap(), 0);
-/// write_system.run((), world);
-/// // Note how the read local is still 0 due to the locals not being shared.
-/// assert_eq!(read_system.run((), world).unwrap(), 0);
+/// // Counter is initialized to u32's default value of 0, and increases to 1 on first run.
+/// assert_eq!(counter_system.run((), world).unwrap(), 1);
+/// // Counter gets the same value and increases to 2 on its second call.
+/// assert_eq!(counter_system.run((), world).unwrap(), 2);
 /// ```
 ///
 /// A simple way to set a different default value for a local is by wrapping the value with an Option.
 ///
 /// ```
 /// # use bevy_ecs::prelude::*;
 /// # let world = &mut World::default();
-/// fn counter_from_10(mut count: Local<Option<usize>>) -> usize {
+/// fn counter_from_10(mut count: Local<Option<u32>>) -> u32 {
 ///     let count = count.get_or_insert(10);
 ///     *count += 1;
 ///     *count
@@ -1022,6 +1022,46 @@ unsafe impl<'w> SystemParam for DeferredWorld<'w> {
 /// assert_eq!(counter_system.run((), world).unwrap(), 12);
 /// ```
 ///
+/// A system having multiple locals with the same type are distinct values.
+///
+/// ```
+/// # use bevy_ecs::prelude::*;
+/// # let world = &mut World::default();
+/// fn double_counter(mut count: Local<u32>, mut double_count: Local<u32>) -> (u32, u32) {
+///     *count += 1;
+///     *double_count += 2;
+///     (*count, *double_count)
+/// }
+/// let mut counter_system = IntoSystem::into_system(double_counter);
+/// counter_system.initialize(world);
+///
+/// assert_eq!(counter_system.run((), world).unwrap(), (1, 2));
+/// // Counter is only increased by 1 on subsequent runs.
+/// assert_eq!(counter_system.run((), world).unwrap(), (2, 4));
+/// ```
+///
+/// This example shows that two systems using the same type for their own local get different locals.
+///
+/// ```
+/// # use bevy_ecs::prelude::*;
+/// # let world = &mut World::default();
+/// fn write_to_local(mut local: Local<usize>) {
+///     *local = 42;
+/// }
+/// fn read_from_local(local: Local<usize>) -> usize {
+///     *local
+/// }
+/// let mut write_system = IntoSystem::into_system(write_to_local);
+/// let mut read_system = IntoSystem::into_system(read_from_local);
+/// write_system.initialize(world);
+/// read_system.initialize(world);
+///
+/// assert_eq!(read_system.run((), world).unwrap(), 0);
+/// write_system.run((), world);
+/// // The read local is still 0 due to the locals not being shared.
+/// assert_eq!(read_system.run((), world).unwrap(), 0);
+/// ```
+///
 /// N.B. A [`Local`]s value cannot be read or written to outside of the containing system.
 /// To add configuration to a system, convert a capturing closure into the system instead:
 ///
@@ -1085,6 +1125,7 @@ where
 }
 
 // SAFETY: only local state is accessed
+/// System private persistent value
 unsafe impl<'a, T: FromWorld + Send + 'static> SystemParam for Local<'a, T> {
     type State = SyncCell<T>;
     type Item<'w, 's> = Local<'s, T>;