Improved documentation for Events (#1669)

Explains subtle behavior more explicitly, documents `add_event`, mentions `EventWriter`.

Co-authored-by: Carter Anderson <mcanders1@gmail.com>

crates/bevy_app/src/app_builder.rs

@@ -207,6 +207,10 @@ impl AppBuilder {
             .add_stage(CoreStage::Last, SystemStage::parallel())
     }
 
+    /// Setup the application to manage events of type `T`.
+    ///
+    /// This is done by adding a `Resource` of type `Events::<T>`,
+    /// and inserting a `Events::<T>::update_system` system into `CoreStage::First`.
     pub fn add_event<T>(&mut self) -> &mut Self
     where
         T: Component,

crates/bevy_app/src/event.rs

@@ -56,11 +56,23 @@ enum State {
 }
 
 /// An event collection that represents the events that occurred within the last two
-/// [Events::update] calls. Events can be cheaply read using an [EventReader]. This collection is
+/// [`Events::update`] calls.
-/// meant to be paired with a system that calls [Events::update] exactly once per update/frame.
+/// Events can be written to using an [`EventWriter`]
-/// [Events::update_system] is a system that does this. [EventReader]s are expected to read events
+/// and are typically cheaply read using an [`EventReader`].
-/// from this collection at least once per update/frame. If events are not handled within one
+///
-/// frame/update, they will be dropped.
+/// Each event can be consumed by multiple systems, in parallel,
+/// with consumption tracked by the [`EventReader`] on a per-system basis.
+///
+/// This collection is meant to be paired with a system that calls
+/// [`Events::update`] exactly once per update/frame.
+///
+/// [`Events::update_system`] is a system that does this, typically intialized automatically using
+/// [`AppBuilder::add_event`]. [EventReader]s are expected to read events from this collection at
+/// least once per loop/frame.  
+/// Events will persist across a single frame boundary and so ordering of event producers and
+/// consumers is not critical (although poorly-planned ordering may cause accumulating lag).
+/// If events are not handled by the end of the frame after they are updated, they will be
+/// dropped silently.
 ///
 /// # Example
 /// ```
@@ -100,7 +112,9 @@ enum State {
 /// The buffers in [Events] will grow indefinitely if [Events::update] is never called.
 ///
 /// An alternative call pattern would be to call [Events::update] manually across frames to control
-/// when events are cleared. However this complicates consumption
+/// when events are cleared.
+/// This complicates consumption and risks ever-expanding memory usage if not cleaned up,
+/// but can be done by adding your event as a resource instead of using [`AppBuilder::add_event`].
 #[derive(Debug)]
 pub struct Events<T> {
     events_a: Vec<EventInstance<T>>,

crates/bevy_ecs/src/schedule/stage.rs

@@ -173,18 +173,21 @@ impl SystemStage {
     pub fn parallel_systems(&self) -> &[impl SystemContainer] {
         &self.parallel
     }
+
     /// Topologically sorted exclusive systems that want to be run at the start of the stage.
     ///
     /// Note that systems won't be fully-formed until the stage has been run at least once.
     pub fn exclusive_at_start_systems(&self) -> &[impl SystemContainer] {
         &self.exclusive_at_start
     }
+
     /// Topologically sorted exclusive systems that want to be run at the end of the stage.
     ///
     /// Note that systems won't be fully-formed until the stage has been run at least once.
     pub fn exclusive_at_end_systems(&self) -> &[impl SystemContainer] {
         &self.exclusive_at_end
     }
+
     /// Topologically sorted exclusive systems that want to be run after parallel systems but
     /// before the application of their command buffers.
     ///

crates/bevy_ecs/src/schedule/state.rs

@@ -188,7 +188,8 @@ impl<T: Component + Clone + Eq> State<T> {
 
     /// Creates a driver set for the State.
     ///
-    /// Important note: this set must be inserted **before** all other state-dependant sets to work properly!
+    /// Important note: this set must be inserted **before** all other state-dependant sets to work
+    /// properly!
     pub fn make_driver() -> SystemSet {
         SystemSet::default().with_run_criteria(state_cleaner::<T>.system())
     }
@@ -203,7 +204,8 @@ impl<T: Component + Clone + Eq> State<T> {
     }
 
     /// Schedule a state change that replaces the full stack with the given state.
-    /// This will fail if there is a scheduled operation, or if the given `state` matches the current state
+    /// This will fail if there is a scheduled operation, or if the given `state` matches the
+    /// current state
     pub fn set_next(&mut self, state: T) -> Result<(), StateError> {
         if self.stack.last().unwrap() == &state {
             return Err(StateError::AlreadyInState);
@@ -217,7 +219,8 @@ impl<T: Component + Clone + Eq> State<T> {
         Ok(())
     }
 
-    /// Same as [Self::set_next], but if there is already a next state, it will be overwritten instead of failing
+    /// Same as [Self::set_next], but if there is already a next state, it will be overwritten
+    /// instead of failing
     pub fn overwrite_next(&mut self, state: T) -> Result<(), StateError> {
         if self.stack.last().unwrap() == &state {
             return Err(StateError::AlreadyInState);
@@ -241,7 +244,8 @@ impl<T: Component + Clone + Eq> State<T> {
         Ok(())
     }
 
-    /// Same as [Self::set_push], but if there is already a next state, it will be overwritten instead of failing
+    /// Same as [Self::set_push], but if there is already a next state, it will be overwritten
+    /// instead of failing
     pub fn overwrite_push(&mut self, state: T) -> Result<(), StateError> {
         if self.stack.last().unwrap() == &state {
             return Err(StateError::AlreadyInState);
@@ -265,7 +269,8 @@ impl<T: Component + Clone + Eq> State<T> {
         Ok(())
     }
 
-    /// Same as [Self::set_pop], but if there is already a next state, it will be overwritten instead of failing
+    /// Same as [Self::set_pop], but if there is already a next state, it will be overwritten
+    /// instead of failing
     pub fn overwrite_pop(&mut self) -> Result<(), StateError> {
         if self.stack.len() == 1 {
             return Err(StateError::StackEmpty);

crates/bevy_render/src/texture/texture_descriptor.rs

@@ -58,7 +58,8 @@ pub enum StorageTextureAccess {
     /// ```
     WriteOnly,
     /// The texture can be both read and written in the shader.
-    /// `wgpu::Features::STORAGE_TEXTURE_ACCESS_READ_WRITE` must be enabled to use this access mode.
+    /// `wgpu::Features::STORAGE_TEXTURE_ACCESS_READ_WRITE` must be enabled to use this access
+    /// mode.
     ///
     /// Example GLSL syntax:
     /// ```cpp,ignore