[Merged by Bors] - Improve bevy_ecs and bevy_app API docs where referenced by the new Bevy Book

crates/bevy_app/src/app.rs

@@ -9,9 +9,10 @@ use bevy_utils::tracing::info_span;
 #[allow(clippy::needless_doctest_main)]
 /// Containers of app logic and data
 ///
-/// App store the ECS World, Resources, Schedule, and Executor. They also store the "run" function
-/// of the App, which by default executes the App schedule once. Apps are constructed using the
-/// builder pattern.
+/// Bundles together the necessary elements, like [`World`] and [`Schedule`], to create
+/// an ECS based application. It also stores a pointer to a
+/// [runner function](AppBuilder::set_runner), which by default executes the App schedule
+/// once. Apps are constructed with the builder pattern, using the [`AppBuilder`] struct.
 ///
 /// ## Example
 /// Here is a simple "Hello World" Bevy app:
@@ -50,10 +51,13 @@ fn run_once(mut app: App) {
 }
 
 impl App {
+ /// Returns an [`AppBuilder`] with a basic structure that can be configured further
+ /// to create an `App`.
  pub fn build() -> AppBuilder {
  AppBuilder::default()
  }
 
+ /// Advances the execution of the [`Schedule`] by one cycle.
  pub fn update(&mut self) {
  #[cfg(feature = "trace")]
  let bevy_frame_update_span = info_span!("frame");
@@ -62,6 +66,7 @@ impl App {
  self.schedule.run(&mut self.world);
  }
 
+ /// Calls the runner function of the `App`.
  pub fn run(mut self) {
  #[cfg(feature = "trace")]
  let bevy_app_run_span = info_span!("bevy_app");

crates/bevy_app/src/app_builder.rs

@@ -15,8 +15,9 @@ use bevy_ecs::{
 use bevy_utils::tracing::debug;
 use std::{fmt::Debug, hash::Hash};
 
-/// Configure [App]s using the builder pattern
+/// Configure [`App`]s using the builder pattern.
 pub struct AppBuilder {
+ /// The app being configured.
  pub app: App,
 }
 
@@ -43,18 +44,17 @@ impl Default for AppBuilder {
 }
 
 impl AppBuilder {
+ /// Returns an `AppBuilder` without any configuration.
+ ///
+ /// For an `AppBuilder` with [default stages](AppBuilder::add_default_stages) included,
+ /// use `AppBuilder::default`.
  pub fn empty() -> AppBuilder {
  AppBuilder {
  app: App::default(),
  }
  }
 
- /// Start the application (through main runner)
- ///
- /// Runs the application main loop.
- ///
- /// Usually the main loop is handled by Bevy integrated plugins (`winit`), but
- /// but one can also set the runner function through [`AppBuilder::set_runner`].
+ /// Starts the application by calling the app's [runner function](Self::set_runner).
  ///
  /// ## Example
  /// ```
@@ -70,24 +70,31 @@ impl AppBuilder {
  app.run();
  }
 
+ /// Returns a shared reference to the ECS [`World`] stored in the app.
  pub fn world(&mut self) -> &World {
  &self.app.world
  }
 
+ /// Returns a unique, mutable reference to the ECS [`World`] stored in the app.
  pub fn world_mut(&mut self) -> &mut World {
  &mut self.app.world
  }
 
+ /// Stores the given [`World`] as the app's world.
  pub fn set_world(&mut self, world: World) -> &mut Self {
  self.app.world = world;
  self
  }
 
+ /// Adds a [`Stage`] with the given `label` to the last position of the app's
+ /// [`Schedule`].
  pub fn add_stage<S: Stage>(&mut self, label: impl StageLabel, stage: S) -> &mut Self {
  self.app.schedule.add_stage(label, stage);
  self
  }
 
+ /// Adds a [`Stage`] with the given `label` to the app's [`Schedule`], located
+ /// immediately after the stage labeled by `target`.
  pub fn add_stage_after<S: Stage>(
  &mut self,
  target: impl StageLabel,
@@ -98,6 +105,8 @@ impl AppBuilder {
  self
  }
 
+ /// Adds a [`Stage`] with the given `label` to the app's [`Schedule`], located
+ /// immediately before the stage labeled by `target`.
  pub fn add_stage_before<S: Stage>(
  &mut self,
  target: impl StageLabel,
@@ -108,6 +117,8 @@ impl AppBuilder {
  self
  }
 
+ /// Adds a [`Stage`] with the given `label` to the last position of the
+ /// [startup schedule](Self::add_default_stages).
  pub fn add_startup_stage<S: Stage>(&mut self, label: impl StageLabel, stage: S) -> &mut Self {
  self.app
  .schedule
@@ -117,6 +128,8 @@ impl AppBuilder {
  self
  }
 
+ /// Adds a [startup stage](Self::add_default_stages) with the given `label` of type
+ /// [`StartupStage`], immediately after the stage labeled by `target`.
  pub fn add_startup_stage_after<S: Stage>(
  &mut self,
  target: impl StageLabel,
@@ -131,6 +144,8 @@ impl AppBuilder {
  self
  }
 
+ /// Adds a [startup stage](Self::add_default_stages) with the given `label` of type
+ /// [`StartupStage`], immediately before the stage labeled by `target`.
  pub fn add_startup_stage_before<S: Stage>(
  &mut self,
  target: impl StageLabel,
@@ -145,6 +160,10 @@ impl AppBuilder {
  self
  }
 
+ /// Fetches the [`Stage`] of type `T` marked with `label` from the [`Schedule`], then
+ /// executes `func` using the stage as parameter.
+ ///
+ /// See [`Schedule::stage`] for more details.
  pub fn stage<T: Stage, F: FnOnce(&mut T) -> &mut T>(
  &mut self,
  label: impl StageLabel,
@@ -154,17 +173,7 @@ impl AppBuilder {
  self
  }
 
- /// Adds a system that runs every time `app.update()` is called by the runner
- ///
- /// Systems are the main building block in the Bevy ECS app model. You can define
- /// normal rust functions, and call `.system()` to make them be Bevy systems.
- ///
- /// System functions can have parameters, through which one can query and
- /// mutate Bevy ECS states.
- /// See [The Bevy Book](https://bevyengine.org/learn/book/introduction/) for more information.
- ///
- /// Systems are run in parallel, and the execution order is not deterministic.
- /// If you want more fine-grained control for order, see [`AppBuilder::add_system_to_stage`].
+ /// Adds a system to the [update stage](Self::add_default_stages) of the app's [`Schedule`].
  ///
  /// For adding a system that runs only at app startup, see [`AppBuilder::add_startup_system`].
  ///
@@ -184,10 +193,12 @@ impl AppBuilder {
  self.add_system_to_stage(CoreStage::Update, system)
  }
 
+ /// Adds a [`SystemSet`] to the [update stage](Self::add_default_stages).
  pub fn add_system_set(&mut self, system_set: SystemSet) -> &mut Self {
  self.add_system_set_to_stage(CoreStage::Update, system_set)
  }
 
+ /// Adds a system to the [`Stage`] identified by `stage_label`.
  pub fn add_system_to_stage(
  &mut self,
  stage_label: impl StageLabel,
@@ -197,6 +208,7 @@ impl AppBuilder {
  self
  }
 
+ /// Adds a [`SystemSet`] to the [`Stage`] identified by `stage_label`.
  pub fn add_system_set_to_stage(
  &mut self,
  stage_label: impl StageLabel,
@@ -208,10 +220,7 @@ impl AppBuilder {
  self
  }
 
- /// Adds a system that is run once at application startup
- ///
- /// Startup systems run exactly once BEFORE all other systems. These are generally used for
- /// app initialization code (ex: adding entities and resources).
+ /// Adds a system to the [startup stage](Self::add_default_stages) of the app's [`Schedule`].
  ///
  /// * For adding a system that runs for every frame, see [`AppBuilder::add_system`].
  /// * For adding a system to specific stage, see [`AppBuilder::add_system_to_stage`].
@@ -236,6 +245,10 @@ impl AppBuilder {
  self.add_startup_system_set_to_stage(StartupStage::Startup, system_set)
  }
 
+ /// Adds a system to the [startup schedule](Self::add_default_stages), in the stage
+ /// identified by `stage_label`.
+ ///
+ /// Stage label must be of type [`StartupStage`].
  pub fn add_startup_system_to_stage(
  &mut self,
  stage_label: impl StageLabel,
@@ -287,6 +300,26 @@ impl AppBuilder {
  .add_system_set_to_stage(stage, State::<T>::get_driver())
  }
 
+ /// Adds utility stages to the [`Schedule`], giving it a standardized structure.
+ ///
+ /// Adding those stages is necessary to make work some core engine features, like
+ /// adding systems without specifying a stage, or registering events. This is however
+ /// done by default by calling `AppBuilder::default`, which is in turn called by
+ /// [`App::build`].
+ ///
+ /// # The stages
+ ///
+ /// All the added stages, with the exception of the startup stage, run every time the
+ /// schedule is invoked. The most relevant stages are the following, in order of execution:
+ /// - **First:** Runs at the very start of the schedule execution cycle, even before the
+ /// startup stage.
+ /// - **Startup:** It is actually a schedule containing sub-stages. Runs only once
+ /// when the app starts.
+ /// - **Update:** Stage intended for user defined logic.
+ /// - **Last:** Runs right before the end of the schedule execution cycle.
+ ///
+ /// The labels for those stages are defined in the [`CoreStage`] and [`StartupStage`]
+ /// `enum`s.
  pub fn add_default_stages(&mut self) -> &mut Self {
  self.add_stage(CoreStage::First, SystemStage::parallel())
  .add_stage(
@@ -320,7 +353,7 @@ impl AppBuilder {
  /// A resource in Bevy represents globally unique data. Resources must be added to Bevy Apps
  /// before using them. This happens with [`AppBuilder::insert_resource`].
  ///
- /// See also `init_resource` for resources that implement `Default` or [`FromResources`].
+ /// See also `init_resource` for resources that implement `Default` or `FromResources`.
  ///
  /// ## Example
  /// ```
@@ -365,9 +398,9 @@ impl AppBuilder {
  self
  }
 
- /// Initialize a resource in the current [App], if it does not exist yet
+ /// Initialize a resource in the current [`App`], if it does not exist yet
  ///
- /// Adds a resource that implements `Default` or [`FromResources`] trait.
+ /// Adds a resource that implements `Default` or `FromResources` trait.
  /// If the resource already exists, `init_resource` does nothing.
  ///
  /// ## Example
@@ -403,6 +436,10 @@ impl AppBuilder {
  self
  }
 
+ /// Initialize a non-send resource in the current [`App`], if it does not exist yet.
+ ///
+ /// Adds a resource that implements `Default` or `FromResources` trait.
+ /// If the resource already exists, it does nothing.
  pub fn init_non_send_resource<R>(&mut self) -> &mut Self
  where
  R: FromWorld + 'static,
@@ -415,12 +452,14 @@ impl AppBuilder {
  self
  }
 
- /// Sets the main runner loop function for this Bevy App
+ /// Sets the function that will be called when the app is run.
  ///
- /// Usually the main loop is handled by Bevy integrated plugins ([`WinitPlugin`]), but
- /// in some cases one might wish to implement their own main loop.
+ /// The runner function (`run_fn`) is called only once by [`AppBuilder::run`]. If the
+ /// presence of a main loop in the app is desired, it is responsibility of the runner
+ /// function to provide it.
  ///
- /// This method sets the main loop function, overwriting a previous runner if any.
+ /// The runner function is usually not set manually, but by Bevy integrated plugins
+ /// (e.g. winit plugin).
  ///
  /// ## Example
  /// ```
@@ -531,17 +570,19 @@ impl AppBuilder {
  self
  }
 
- /// Registers a new component using the given [ComponentDescriptor]. Components do not need to
- /// be manually registered. This just provides a way to override default configuration.
- /// Attempting to register a component with a type that has already been used by [World]
- /// will result in an error.
+ /// Registers a new component using the given [ComponentDescriptor].
+ ///
+ /// Components do not need to be manually registered. This just provides a way to
+ /// override default configuration. Attempting to register a component with a type
+ /// that has already been used by [World] will result in an error.
  ///
  /// See [World::register_component]
  pub fn register_component(&mut self, descriptor: ComponentDescriptor) -> &mut Self {
  self.world_mut().register_component(descriptor).unwrap();
  self
  }
 
+ /// Adds the type `T` to the type registry resource.
  #[cfg(feature = "bevy_reflect")]
  pub fn register_type<T: bevy_reflect::GetTypeRegistration>(&mut self) -> &mut Self {
  {

crates/bevy_app/src/lib.rs

@@ -26,9 +26,14 @@ pub mod prelude {
 use bevy_ecs::schedule::StageLabel;
 
 /// The names of the default App stages
+///
+/// The relative stages are added by [`AppBuilder::add_default_stages`].
 #[derive(Debug, Hash, PartialEq, Eq, Clone, StageLabel)]
 pub enum CoreStage {
- /// Runs once at the beginning of the app.
+ /// Runs only once at the beginning of the app.
+ ///
+ /// Consists in more sub-stages defined in [`StartupStage`]. Systems added here are
+ /// referred to as "startup systems".
  Startup,
  /// Name of app stage that runs before all other app stages
  First,

crates/bevy_ecs/src/schedule/mod.rs

@@ -173,6 +173,30 @@ impl Schedule {
  })
  }
 
+ /// Fetches the [`Stage`] of type `T` marked with `label`, then executes `func` using the
+ /// stage as parameter.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// # use bevy_ecs::schedule::Schedule;
+ /// # use bevy_ecs::schedule::SystemSet;
+ /// # use bevy_ecs::schedule::SystemStage;
+ /// # use bevy_ecs::system::IntoSystem;
+ /// #
+ /// # let mut schedule = Schedule::default();
+ /// # schedule.add_stage("update", SystemStage::parallel());
+ /// #
+ /// schedule.stage("update", |stage: &mut SystemStage| {
+ /// stage.add_system(quit_game_keyboard_shortcuts_system.system())
+ /// });
+ /// #
+ /// # fn quit_game_keyboard_shortcuts_system() {}
+ /// ```
+ ///
+ /// # Panics
+ ///
+ /// Panics if `label` refers to a non-existing stage, or if it's not of type `T`.
  pub fn stage<T: Stage, F: FnOnce(&mut T) -> &mut T>(
  &mut self,
  label: impl StageLabel,

crates/bevy_ecs/src/system/mod.rs

@@ -1,3 +1,21 @@
+//! The behavior building block of an ECS application.
+//!
+//! Systems define how an ECS based application behave. They have to be registered to a
+//! [`SystemStage`](crate::schedule::SystemStage) to be able to run. A system is usually written as a normal function,
+//! on which the [`.system()`](IntoSystem::system) trait extension method is used, to turn it
+//! into a Bevy system.
+//!
+//! System functions can have parameters, through which one can query and mutate Bevy ECS
+//! states. Some limitations on allowed parameters apply (See [`SystemParam`]).
+//!
+//! While the execution of systems is usually parallel and not deterministic, there are two
+//! ways to determine a certain degree of execution order:
+//!
+//! - **System Stages:** They determine hard execution synchronization boundaries inside of
+//! which systems run in parallel by default.
+//! - **Labeling:** First, systems are labeled upon creation by calling `.label()`. Then,
+//! methods such as `.before()` and `.after()` are appended to systems to determine
+//! execution order in respect to other systems.
 mod commands;
 mod exclusive_system;
 mod function_system;