Document SystemState + exclusive system patterns

crates/bevy_ecs/src/system/function_system.rs

@@ -91,6 +91,25 @@ impl SystemMeta {
     #[inline]
     pub fn set_non_send(&mut self) {
         self.flags |= SystemStateFlags::NON_SEND;
+    /// Alternatively, for exclusive systems the ECS can automatically cache a
+    /// `SystemState` for you. The trait [`ExclusiveSystemParam`] is implemented for
+    /// `&'a mut SystemState<P>`, so if your function is an exclusive system
+    /// (takes `&mut World` as its first parameter) you can accept
+    /// `&mut SystemState<...>` directly and the ECS will initialize and persist it
+    /// across invocations. Example:
+    /// ```
+    /// # use bevy_ecs::prelude::*;
+    /// # use bevy_ecs::system::SystemState;
+    /// #
+    /// # #[derive(Message)]
+    /// # struct MyMessage;
+    /// fn exclusive_system(world: &mut World, system_state: &mut SystemState<MessageReader<MyMessage>>) {
+    ///     let mut message_reader = system_state.get_mut(world);
+    ///     for message in message_reader.read() {
+    ///         println!("Hello World!");
+    ///     }
+    /// }
+    /// ```
     }
 
     /// Returns true if the system has deferred [`SystemParam`]'s

crates/bevy_ecs/src/system/system_registry.rs

@@ -500,6 +500,16 @@ impl World {
 
     /// Runs a cached system, registering it if necessary.
     ///
+    /// # Type Inference Note
+    /// If the system returns `()`, you may need to explicitly constrain the output
+    /// type for error handling:
+    ///
+    /// ```rust
+    /// () = world.run_system_cached(my_system)?;
+    /// ```
+    ///
+    /// Without this, Rust may fail to infer the system’s output type and produce
+    /// a `IntoResult<!>` inference error.
     /// See [`World::register_system_cached`] for more information.
     pub fn run_system_cached<O: 'static, M, S: IntoSystem<(), O, M> + 'static>(
         &mut self,
@@ -509,7 +519,18 @@ impl World {
     }
 
     /// Runs a cached system with an input, registering it if necessary.
+    /// Runs a cached system, registering it if necessary.
+    ///
+    /// # Type Inference Note
+    /// If the system returns `()`, you may need to explicitly constrain the output
+    /// type for error handling:
+    ///
+    /// ```rust
+    /// () = world.run_system_cached(my_system)?;
+    /// ```
     ///
+    /// Without this, Rust may fail to infer the system’s output type and produce
+    /// a `IntoResult<!>` inference error.
     /// See [`World::register_system_cached`] for more information.
     pub fn run_system_cached_with<I, O, M, S>(
         &mut self,