Improve AssetEvent docs

crates/bevy_asset/src/event.rs

@@ -45,6 +45,24 @@ impl<A: Asset> From<&AssetLoadFailedEvent<A>> for UntypedAssetLoadFailedEvent {
 }
 
 /// [`Message`]s that occur for a specific loaded [`Asset`], such as "value changed" events and "dependency" events.
+/// Events concerning a specific [`Asset`] value.
+///
+/// Each variant carries the [`AssetId`] of the asset affected by the event. These
+/// messages are emitted by the asset system to notify other systems about
+/// lifecycle changes for individual assets:
+///
+/// - `Added`: a new asset value was inserted into the asset storage.
+/// - `Modified`: an existing asset value has been updated.
+/// - `Removed`: the asset value was removed from the asset storage.
+/// - `Unused`: the last strong handle to the asset was dropped; the asset may
+///   be eligible for cleanup.
+/// - `LoadedWithDependencies`: the asset and all of its recursive dependencies
+///   have been fully loaded and are ready for use.
+///
+/// Note on the `id` fields:
+/// The `id` in every variant is a stable identifier for the asset that the
+/// event refers to. The `id` semantics are consistent across all variants, so
+/// they are documented here rather than on each variant individually.
 #[expect(missing_docs, reason = "Documenting the id fields is unhelpful.")]
 #[derive(Message, Reflect)]
 pub enum AssetEvent<A: Asset> {

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,
@@ -508,8 +518,21 @@ impl World {
         self.run_system_cached_with(system, ())
     }
 
-    /// Runs a cached system with an input, registering it if necessary.
+    /// Runs a cached system with the provided input, registering it if necessary.
+    ///
+    /// This is a more general version of [`World::run_system_cached`], allowing
+    /// callers to supply an explicit system input.
+    ///
+    /// # Type Inference Note
+    /// If the system returns `()`, you may need to explicitly constrain the
+    /// output type for proper error inference:
+    ///
+    /// ```rust
+    /// () = world.run_system_cached_with(my_system, input)?;
+    /// ```
     ///
+    /// 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,