Fill in and update remaining docs

Author: cart

crates/bevy_animation/src/animation_event.rs

@@ -7,13 +7,20 @@ use bevy_ecs::{
     world::DeferredWorld,
 };
 
+/// An [`Event`] that an [`AnimationPlayer`](crate::AnimationPlayer) can trigger when playing an [`AnimationClip`](crate::AnimationClip).
+/// See [`AnimationClip::add_event`](crate::AnimationClip::add_event).
+///
+/// This trait can be derived.
 pub trait AnimationEvent: Clone + for<'a> Event<Trigger<'a> = AnimationEventTrigger> {}
 
+/// The [`Trigger`] implemention for [`AnimationEvent`]. This passes in the [`AnimationPlayer`](crate::AnimationPlayer)
+/// context, and uses that to run any observers that target that entity.
 pub struct AnimationEventTrigger {
+    /// The [`AnimationPlayer`](crate::AnimationPlayer) where this [`AnimationEvent`] occurred.
     pub animation_player: Entity,
 }
 
-impl<E: Event> Trigger<E> for AnimationEventTrigger {
+impl<E: AnimationEvent> Trigger<E> for AnimationEventTrigger {
     fn trigger(
         &mut self,
         world: DeferredWorld,

crates/bevy_core_widgets/src/core_checkbox.rs

@@ -127,6 +127,7 @@ pub struct SetChecked {
 /// ```
 #[derive(EntityEvent)]
 pub struct ToggleChecked {
+    /// The [`Entity`] of the toggled [`CoreCheckbox`]
     pub entity: Entity,
 }
 

crates/bevy_core_widgets/src/core_slider.rs

@@ -519,6 +519,7 @@ pub struct SetSliderValue {
     pub change: SliderValueChange,
 }
 
+/// The type of slider value change to apply in [`SetSliderValue`].
 #[derive(Clone)]
 pub enum SliderValueChange {
     /// Set the slider value to a specific value.

crates/bevy_ecs/macros/src/component.rs

@@ -86,6 +86,7 @@ pub fn derive_entity_event(input: TokenStream) -> TokenStream {
                 processed_attrs.push(AUTO_PROPAGATE);
                 Ok(())
             }
+            #[allow(deprecated)]
             Some(ident) if ident == TRAVERSAL => {
                 Err(meta.error(
                     "`traversal` has been renamed to `propagate`, use that instead. If you were writing `traversal = &'static ChildOf`, you can now just write `propagate`, which defaults to the `ChildOf` traversal."

crates/bevy_ecs/src/event/buffered_event/registry.rs

@@ -17,13 +17,13 @@ struct RegisteredEvent {
     update: unsafe fn(MutUntyped),
 }
 
-/// A registry of all of the [`Events`] in the [`World`], used by [`event_update_system`](crate::event::update::event_update_system)
+/// A registry of all of the [`Events`] in the [`World`], used by [`event_update_system`](crate::event::event_update_system)
 /// to update all of the events.
 #[derive(Resource, Default)]
 pub struct EventRegistry {
     /// Should the events be updated?
     ///
-    /// This field is generally automatically updated by the [`signal_event_update_system`](crate::event::update::signal_event_update_system).
+    /// This field is generally automatically updated by the [`signal_event_update_system`](crate::event::signal_event_update_system).
     pub should_update: ShouldUpdateEvents,
     event_updates: Vec<RegisteredEvent>,
 }

crates/bevy_ecs/src/event/mod.rs

@@ -229,6 +229,23 @@ pub trait Event: Send + Sync + Sized + 'static {
 ///     entity: Entity,
 /// }
 /// ```
+
+/// You can also _stop_ propagation like this:
+/// ```
+/// # use bevy_ecs::prelude::*;
+/// # #[derive(EntityEvent)]
+/// # #[entity_event(propagate)]
+/// # struct Click {
+/// #    entity: Entity,
+/// # }
+/// # fn is_finished_propagating() -> bool { true }
+/// # let mut world = World::default();
+/// world.add_observer(|mut click: On<Click>| {
+///   if is_finished_propagating() {
+///     click.propagate(false);
+///   }
+/// });
+/// ```
 ///
 /// ## Naming and Usage Conventions
 ///
@@ -316,7 +333,7 @@ struct EventWrapperComponent<E: Event>(PhantomData<E>);
 
 /// A unique identifier for an [`Event`], used by [observers].
 ///
-/// You can look up the key for your event by calling the [`Event::event_key`] method.
+/// You can look up the key for your event by calling the [`World::event_key`] method.
 ///
 /// [observers]: crate::observer
 #[derive(Debug, Copy, Clone, Hash, Ord, PartialOrd, Eq, PartialEq)]

crates/bevy_ecs/src/event/trigger.rs

@@ -9,7 +9,21 @@ use crate::{
 use bevy_ptr::PtrMut;
 use core::marker::PhantomData;
 
+/// [`Trigger`] determines _how_ an [`Event`] is triggered when [`World::trigger`](crate::world::World::trigger) is called.
+/// This decides which [`Observer`](crate::observer::Observer)s will run, what data gets passed to them, and the order they will
+/// be executed in.
+///
+/// Implementing [`Trigger`] is "advanced-level" terrority, and is generally unnecessary unless you are developing highly specialized
+/// [`Event`] trigger logic.
+///
+/// Bevy comes with a number of built-in [`Trigger`] implementations (see their documentation for more info):
+/// - [`GlobalTrigger`]: The [`Event`] derive defaults to using this
+/// - [`EntityTrigger`]: The [`EntityEvent`](crate::event::EntityEvent) derive defaults to using this
+/// - [`PropagateEntityTrigger`]: The [`EntityEvent`](crate::event::EntityEvent) derive uses this when propagation is enabled.
+/// - [`EntityComponentsTrigger`]: Used by Bevy's [component lifecycle events](crate::lifecycle).
 pub trait Trigger<E: Event> {
+    /// Trigger the given `event`, running every [`Observer`](crate::observer::Observer) that matches the `event`, as defined by this
+    /// [`Trigger`] and the state stored on `self`.
     fn trigger(
         &mut self,
         world: DeferredWorld,
@@ -19,6 +33,10 @@ pub trait Trigger<E: Event> {
     );
 }
 
+/// A [`Trigger`] that runs _every_ "global" [`Observer`](crate::observer::Observer) (ex: registered via [`World::add_observer`](crate::world::World::add_observer))
+/// that matches the given [`Event`].
+///
+/// The [`Event`] derive defaults to using this [`Trigger`], and it is usable for any [`Event`] type.
 #[derive(Default)]
 pub struct GlobalTrigger;
 
@@ -58,6 +76,14 @@ impl GlobalTrigger {
     }
 }
 
+/// An [`EntityEvent`] [`Trigger`] that does two things:
+/// - Runs all "global" [`Observer`] (ex: registered via [`World::add_observer`](crate::world::World::add_observer))
+/// that matches the given [`Event`]. This is the same behavior as [`GlobalTrigger`].
+/// - Runs every "entity scoped" [`Observer`] that watches the given [`EntityEvent::event_target`] entity.
+///
+/// The [`EntityEvent`] derive defaults to using this [`Trigger`], and it is usable for any [`EntityEvent`] type.
+///
+/// [`Observer`]: crate::observer::Observer
 #[derive(Default)]
 pub struct EntityTrigger;
 
@@ -81,8 +107,8 @@ impl<E: EntityEvent> Trigger<E> for EntityTrigger {
     }
 }
 
-/// Trigger observers listening for the given entity event.
-/// The `target_entity` should match the `EntityEvent::entity` on `event` for logical correctness.
+/// Trigger observers watching for the given entity event.
+/// The `target_entity` should match the [`EntityEvent::event_target`] on `event` for logical correctness.
 // Note: this is not an EntityTrigger method because we want to reuse this logic for the entity propagation trigger
 #[inline(never)]
 pub fn trigger_entity_internal(
@@ -120,9 +146,22 @@ pub fn trigger_entity_internal(
     }
 }
 
+/// An [`EntityEvent`] [`Trigger`] that behaves like [`EntityTrigger`], but "propagates" the event
+/// using an [`Entity`] [`Traversal`]. At each step in the propagation, the [`EntityTrigger`] logic will
+/// be run, until [`PropagateEntityTrigger::propagate`] is false, or there are no entities left to traverse.
+///
+/// This is used by the [`EntityEvent`] derive when `#[entity_event(propagate)]` is enabled. It is usable by every
+/// [`EntityEvent`] type.
+///
+/// If `AUTO_PROPAGATE` is `true`, [`PropagateEntityTrigger::propagate`] will default to `true`.
 pub struct PropagateEntityTrigger<const AUTO_PROPAGATE: bool, E: EntityEvent, T: Traversal<E>> {
+    /// The original [`Entity`] the [`Event`] was _first_ triggered for.
     pub original_event_target: Entity,
+
+    /// Whether or not to continue propagating using the `T` [`Traversal`]. If this is false,
+    /// The [`Traversal`] will stop on the current entity.
     pub propagate: bool,
+
     _marker: PhantomData<(E, T)>,
 }
 
@@ -185,6 +224,11 @@ impl<const AUTO_PROPAGATE: bool, E: EntityEvent, T: Traversal<E>> Trigger<E>
     }
 }
 
+/// An [`EntityEvent`] [`Trigger`] that, in addition to behaving like a normal [`EntityTrigger`], _also_ runs observers
+/// that watch for components that match the slice of [`ComponentId`]s referenced in [`EntityComponentsTrigger`]. This includes
+/// both _global_ observers of those components and "entity scoped" observers that watch the [`EntityEvent::event_target`].
+///
+/// This is used by Bevy's built-in [lifecycle events](crate::lifecycle).
 #[derive(Default)]
 pub struct EntityComponentsTrigger<'a>(pub &'a [ComponentId]);
 
@@ -220,7 +264,7 @@ impl<'a> EntityComponentsTrigger<'a> {
             trigger_context,
         );
 
-        // Trigger observers listening to this trigger targeting a specific component
+        // Trigger observers watching for a specific component
         for id in self.0 {
             if let Some(component_observers) = observers.component_observers().get(id) {
                 for (observer, runner) in component_observers.global_observers() {

crates/bevy_ecs/src/lifecycle.rs

@@ -43,7 +43,7 @@
 //!
 //! Despite the absence of generics, each lifecycle event is associated with a specific component.
 //! When defining a component hook for a [`Component`] type, that component is used.
-//! When listening to lifecycle events for observers, the `B: Bundle` generic is used.
+//! When observers watch lifecycle events, the `B: Bundle` generic is used.
 //!
 //! Each of these lifecycle events also corresponds to a fixed [`ComponentId`],
 //! which are assigned during [`World`] initialization.

crates/bevy_ecs/src/observer/centralized_storage.rs

@@ -18,20 +18,20 @@ use crate::{
 
 /// An internal lookup table tracking all of the observers in the world.
 ///
-/// Stores a cache mapping trigger ids to the registered observers.
+/// Stores a cache mapping event ids to their registered observers.
 /// Some observer kinds (like [lifecycle](crate::lifecycle) observers) have a dedicated field,
 /// saving lookups for the most common triggers.
 ///
 /// This can be accessed via [`World::observers`].
 #[derive(Default, Debug)]
 pub struct Observers {
-    // Cached ECS observers to save a lookup most common triggers.
+    // Cached ECS observers to save a lookup for high-traffic built-in event types.
     add: CachedObservers,
     insert: CachedObservers,
     replace: CachedObservers,
     remove: CachedObservers,
     despawn: CachedObservers,
-    // Map from trigger type to set of observers listening to that trigger
+    // Map from event type to set of observers watching for that event
     cache: HashMap<EventKey, CachedObservers>,
 }
 
@@ -111,28 +111,28 @@ impl Observers {
 /// This is stored inside of [`Observers`], specialized for each kind of observer.
 #[derive(Default, Debug)]
 pub struct CachedObservers {
-    // Observers listening for any time this event is fired, regardless of target
-    // This will also respond to events targeting specific components or entities
+    /// Observers watching for any time this event is triggered, regardless of target.
+    /// These will also respond to events targeting specific components or entities
     pub(super) global_observers: ObserverMap,
-    // Observers listening for this trigger fired at a specific component
+    /// Observers watching for triggers of events for a specific component
     pub(super) component_observers: HashMap<ComponentId, CachedComponentObservers>,
-    // Observers listening for this trigger fired at a specific entity
+    /// Observers watching for triggers of events for a specific entity
     pub(super) entity_observers: EntityHashMap<ObserverMap>,
 }
 
 impl CachedObservers {
-    /// Returns the observers listening for this trigger, regardless of target.
-    /// These observers will also respond to events targeting specific components or entities.
+    /// Observers watching for any time this event is triggered, regardless of target.
+    /// These will also respond to events targeting specific components or entities
     pub fn global_observers(&self) -> &ObserverMap {
         &self.global_observers
     }
 
-    /// Returns the observers listening for this trigger targeting components.
+    /// Returns observers watching for triggers of events for a specific component.
     pub fn component_observers(&self) -> &HashMap<ComponentId, CachedComponentObservers> {
         &self.component_observers
     }
 
-    /// Returns the observers listening for this trigger targeting entities.
+    /// Returns observers watching for triggers of events for a specific entity.
     pub fn entity_observers(&self) -> &EntityHashMap<ObserverMap> {
         &self.entity_observers
     }
@@ -146,20 +146,19 @@ pub type ObserverMap = EntityHashMap<ObserverRunner>;
 /// This is stored inside of [`CachedObservers`].
 #[derive(Default, Debug)]
 pub struct CachedComponentObservers {
-    // Observers listening to events targeting this component, but not a specific entity
+    // Observers watching for events targeting this component, but not a specific entity
     pub(super) global_observers: ObserverMap,
-    // Observers listening to events targeting this component on a specific entity
+    // Observers wathing for events targeting this component on a specific entity
     pub(super) entity_component_observers: EntityHashMap<ObserverMap>,
 }
 
 impl CachedComponentObservers {
-    /// Returns the observers listening for this trigger, regardless of target.
-    /// These observers will also respond to events targeting specific entities.
+    /// Returns observers watching for events targeting this component, but not a specific entity
     pub fn global_observers(&self) -> &ObserverMap {
         &self.global_observers
     }
 
-    /// Returns the observers listening for this trigger targeting this component on a specific entity.
+    /// Returns observers wathing for events targeting this component on a specific entity
     pub fn entity_component_observers(&self) -> &EntityHashMap<ObserverMap> {
         &self.entity_component_observers
     }

crates/bevy_ecs/src/observer/distributed_storage.rs

@@ -72,7 +72,7 @@ use crate::prelude::ReflectComponent;
 /// world.spawn(Observer::new(|event: On<Speak>| {}));
 /// ```
 ///
-/// Observers are a specialized [`System`] called called an [`ObserverSystem`]. The first parameter must be [`On`], which provides access
+/// Observers are a specialized [`System`] called an [`ObserverSystem`]. The first parameter must be [`On`], which provides access
 /// to the [`Event`], the [`Trigger`], and some additional execution context.
 ///
 /// Because they are systems, they can access arbitrary [`World`] data by adding [`SystemParam`]s:
@@ -123,7 +123,7 @@ use crate::prelude::ReflectComponent;
 /// recursively evaluated until there are no commands left, meaning nested triggers all
 /// evaluate at the same time!
 ///
-/// ## Event [`Trigger`] Behavior
+/// ## Event [`Trigger`] behavior
 ///
 /// Each [`Event`] defines a [`Trigger`] behavior, which determines _which_ observers will run for the given [`Event`] and _how_ they will be run.
 ///
@@ -140,7 +140,7 @@ use crate::prelude::ReflectComponent;
 ///
 /// You can also define your own!
 ///
-/// ## Observer Execution Timing
+/// ## Observer execution timing
 ///
 /// Observers triggered via [`World::trigger`] are evaluated immediately, as are all commands they queue up.
 ///
@@ -174,10 +174,10 @@ use crate::prelude::ReflectComponent;
 /// If an [`EntityEvent`] [`Observer`] targets specific entities, and all of those entities are despawned, the [`Observer`] entity will also be despawned.
 /// This protects against observer "garbage" building up over time.
 ///
-/// ## Component Lifecycle events: Observers vs Hooks
+/// ## Component lifecycle events: Observers vs Hooks
 ///
 /// It is important to note that observers, just like [hooks](crate::lifecycle::ComponentHooks),
-/// can listen to and respond to [lifecycle](crate::lifecycle) events.
+/// can watch for and respond to [lifecycle](crate::lifecycle) events.
 /// Unlike hooks, observers are not treated as an "innate" part of component behavior:
 /// they can be added or removed at runtime, and multiple observers
 /// can be registered for the same lifecycle event for the same component.
@@ -190,12 +190,12 @@ use crate::prelude::ReflectComponent;
 /// This allows hooks to act as constructors and destructors for components,
 /// as they always have the first and final say in the component's lifecycle.
 ///
-/// ## Observer Re-targeting
+/// ## Observer re-targeting
 ///
 /// Currently, [observers cannot be retargeted after spawning](https://github.com/bevyengine/bevy/issues/19587):
 /// despawn and respawn an observer as a workaround.
 ///
-/// ## Internal observer Cache
+/// ## Internal observer cache
 ///
 /// For more efficient observer triggering, Observers make use of the internal [`CachedObservers`](crate::observer::CachedObservers) storage.
 /// In general, this is an implementation detail developers don't need to worry about, but it can be used when implementing custom [`Trigger`](crate::event::Trigger)