[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,10 @@ impl AppBuilder {
         self
     }
 
+    /// Adds a [startup stage](Self::add_default_stages) with the given `label`, immediately
+    /// after the stage labeled by `target`.
+    ///
+    /// The `target` label must refer to a stage inside the startup schedule.
     pub fn add_startup_stage_after<S: Stage>(
         &mut self,
         target: impl StageLabel,
@@ -131,6 +146,10 @@ impl AppBuilder {
         self
     }
 
+    /// Adds a [startup stage](Self::add_default_stages) with the given `label`, immediately
+    /// before the stage labeled by `target`.
+    ///
+    /// The `target` label must refer to a stage inside the startup schedule.
     pub fn add_startup_stage_before<S: Stage>(
         &mut self,
         target: impl StageLabel,
@@ -145,6 +164,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 +177,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 +197,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 +212,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 +224,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`].
@@ -232,10 +245,15 @@ impl AppBuilder {
         self.add_startup_system_to_stage(StartupStage::Startup, system)
     }
 
+    /// Adds a [`SystemSet`] to the [startup stage](Self::add_default_stages)
     pub fn add_startup_system_set(&mut self, system_set: SystemSet) -> &mut Self {
         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 refer to a stage inside the startup schedule.
     pub fn add_startup_system_to_stage(
         &mut self,
         stage_label: impl StageLabel,
@@ -249,6 +267,10 @@ impl AppBuilder {
         self
     }
 
+    /// Adds a [`SystemSet`] to the [startup schedule](Self::add_default_stages), in the stage
+    /// identified by `stage_label`.
+    ///
+    /// `stage_label` must refer to a stage inside the startup schedule.
     pub fn add_startup_system_set_to_stage(
         &mut self,
         stage_label: impl StageLabel,
@@ -287,6 +309,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 +362,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 +407,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 +445,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 +461,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 +579,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/entity/mod.rs

@@ -1,3 +1,27 @@
+//! The handle to an object stored in a [`World`](crate::world::World).
+//!
+//! In Bevy ECS, there is no monolithic data structure for an entity. Instead, the [`Entity`]
+//! `struct` is just an identification number that [`Component`s](crate::component::Component)
+//! can refer to in order to attach meaningful data to it. As the
+//! [book](#) explains, this is a fundamental design choice that has been made to increase
+//! performance and usability.
+//!
+//! # Usage
+//!
+//! In the following list there are links to the methods used to perform common operations
+//! involving entities:
+//!
+//! - **Spawning an empty entity:** use [`Commands::spawn`](crate::system::Commands::spawn).
+//! - **Spawning an entity with components:** use
+//!   [`Commands::spawn_bundle`](crate::system::Commands::spawn_bundle).
+//! - **Adding multiple components to an entity:** use
+//!   [`EntityCommands::insert_bundle`](crate::system::EntityCommands::insert_bundle).
+//! - **Despawning an entity:** use
+//!   [`EntityCommands::despawn`](crate::system::EntityCommands::despawn).
+//! - **Inserting a component to an entity:** use
+//!   [`EntityCommands::insert`](crate::system::EntityCommands::insert).
+//! - **Removing a component to an entity:** use
+//!   [`EntityCommands::remove`](crate::system::EntityCommands::remove).
 mod map_entities;
 mod serde;