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

crates/bevy_app/src/lib.rs

@@ -1,3 +1,6 @@
+//! This crate is about everything concerning the highest-level, application layer of a Bevy
+//! app.
+
 mod app;
 mod plugin;
 mod plugin_group;
@@ -21,9 +24,14 @@ pub mod prelude {
 use bevy_ecs::schedule::StageLabel;
 
 /// The names of the default App stages
+///
+/// The relative stages are added by [`App::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 of the 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/archetype.rs

@@ -1,3 +1,6 @@
+//! Types for defining [`Archetype`]s, collections of entities that have the same set of
+//! components.
+
 use crate::{
     bundle::BundleId,
     component::{ComponentId, StorageType},

crates/bevy_ecs/src/bundle.rs

@@ -1,3 +1,7 @@
+//! Types for handling [`Bundle`]s.
+//!
+//! This module contains the `Bundle` trait and some other helper types.
+
 pub use bevy_ecs_macros::Bundle;
 
 use crate::{
@@ -9,15 +13,35 @@ use crate::{
 use bevy_ecs_macros::all_tuples;
 use std::{any::TypeId, collections::HashMap};
 
-/// An ordered collection of components, commonly used for spawning entities, and adding and
-/// removing components in bulk.
+/// An ordered collection of components.
+///
+/// Commonly used for spawning entities and adding and removing components in bulk. This
+/// trait is automatically implemented for tuples of components: `(ComponentA, ComponentB)`
+/// is a very convenient shorthand when working with one-off collections of components. Note
+/// that both the unit type `()` and `(ComponentA, )` are valid bundles. The unit bundle is
+/// particularly useful for spawning multiple empty entities by using
+/// [`Commands::spawn_batch`](crate::system::Commands::spawn_batch).
+///
+/// # Examples
 ///
-/// Typically, you will simply use `#[derive(Bundle)]` when creating your own `Bundle`.
-/// The `Bundle` trait is automatically implemented for tuples of components:
-/// `(ComponentA, ComponentB)` is a very convenient shorthand when working with one-off collections
-/// of components. Note that both `()` and `(ComponentA, )` are valid tuples.
+/// Typically, you will simply use `#[derive(Bundle)]` when creating your own `Bundle`. Each
+/// struct field is a component:
 ///
-/// You can nest bundles like so:
+/// ```
+/// # use bevy_ecs::prelude::*;
+/// # struct ComponentA;
+/// # struct ComponentB;
+/// # struct ComponentC;
+/// #
+/// #[derive(Bundle)]
+/// struct MyBundle {
+///     a: ComponentA,
+///     b: ComponentB,
+///     c: ComponentC,
+/// }
+/// ```
+///
+/// You can nest bundles using the `#[bundle]` attribute:
 /// ```
 /// # use bevy_ecs::bundle::Bundle;
 ///
@@ -36,10 +60,11 @@ use std::{any::TypeId, collections::HashMap};
 /// ```
 ///
 /// # Safety
-/// [Bundle::component_ids] must return the ComponentId for each component type in the bundle, in the
-/// _exact_ order that [Bundle::get_components] is called.
-/// [Bundle::from_components] must call `func` exactly once for each [ComponentId] returned by
-/// [Bundle::component_ids]
+///
+/// - [Bundle::component_ids] must return the ComponentId for each component type in the bundle, in the
+///   _exact_ order that [Bundle::get_components] is called.
+/// - [Bundle::from_components] must call `func` exactly once for each [ComponentId] returned by
+///   [Bundle::component_ids].
 pub unsafe trait Bundle: Send + Sync + 'static {
     /// Gets this [Bundle]'s component ids, in the order of this bundle's Components
     fn component_ids(components: &mut Components) -> Vec<ComponentId>;

crates/bevy_ecs/src/change_detection.rs

@@ -1,3 +1,5 @@
+//! Types that detect when their internal data mutate.
+
 use crate::component::{Component, ComponentTicks};
 use bevy_reflect::Reflect;
 use std::ops::{Deref, DerefMut};
@@ -136,9 +138,13 @@ pub(crate) struct Ticks<'a> {
 
 /// Unique mutable borrow of a resource.
 ///
+/// See the [`World`](crate::world::World) documentation to see the usage of a resource.
+///
+/// If you need a shared borrow, use [`Res`](crate::system::Res) instead.
+///
 /// # Panics
 ///
-/// Panics when used as a [`SystemParameter`](crate::system::SystemParam) if the resource does not exist.
+/// Panics when used as a [`SystemParam`](crate::system::SystemParam) if the resource does not exist.
 ///
 /// Use `Option<ResMut<T>>` instead if the resource might not always exist.
 pub struct ResMut<'a, T: Component> {
@@ -152,7 +158,7 @@ impl_debug!(ResMut<'a, T>, Component);
 
 /// Unique borrow of a non-[`Send`] resource.
 ///
-/// Only [`Send`] resources may be accessed with the [`ResMut`] [`crate::system::SystemParam`]. In case that the
+/// Only [`Send`] resources may be accessed with the [`ResMut`] [`SystemParam`](crate::system::SystemParam). In case that the
 /// resource does not implement `Send`, this `SystemParam` wrapper can be used. This will instruct
 /// the scheduler to instead run the system on the main thread so that it doesn't send the resource
 /// over to another thread.

crates/bevy_ecs/src/component.rs

@@ -1,3 +1,5 @@
+//! Types for declaring and storing [`Component`]s.
+
 use crate::storage::SparseSetIndex;
 use std::{
     alloc::Layout,

crates/bevy_ecs/src/entity/mod.rs

@@ -1,3 +1,26 @@
+//! Entity handling types.
+//!
+//! 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. This is a fundamental design choice
+//! that has been taken to enhance performance and usability.
+//!
+//! # Usage
+//!
+//! Here 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).
+//! - **Despawning an entity:** use
+//!   [`EntityCommands::despawn`](crate::system::EntityCommands::despawn).
+//! - **Inserting a component to an entity:** use
+//!   [`EntityCommands::insert`](crate::system::EntityCommands::insert).
+//! - **Adding multiple components to an entity:** use
+//!   [`EntityCommands::insert_bundle`](crate::system::EntityCommands::insert_bundle).
+//! - **Removing a component to an entity:** use
+//!   [`EntityCommands::remove`](crate::system::EntityCommands::remove).
 mod map_entities;
 mod serde;
 
@@ -36,9 +59,11 @@ impl Entity {
     /// Creates a new entity reference with a generation of 0.
     ///
     /// # Note
-    /// Spawning a specific `entity` value is rarely the right choice. Most apps should favor [`Commands::spawn`].
-    /// This method should generally only be used for sharing entities across apps, and only when they have a
-    /// scheme worked out to share an ID space (which doesn't happen by default).
+    ///
+    /// Spawning a specific `entity` value is rarely the right choice. Most apps should favor
+    /// [`Commands::spawn`](crate::system::Commands::spawn). This method should generally
+    /// only be used for sharing entities across apps, and only when they have a scheme
+    /// worked out to share an ID space (which doesn't happen by default).
     pub fn new(id: u32) -> Entity {
         Entity { id, generation: 0 }
     }

crates/bevy_ecs/src/event.rs

@@ -1,3 +1,5 @@
+//! Event handling types.
+
 use crate as bevy_ecs;
 use crate::{
     component::Component,

crates/bevy_ecs/src/lib.rs

@@ -12,6 +12,7 @@ pub mod storage;
 pub mod system;
 pub mod world;
 
+/// Most commonly used re-exported types.
 pub mod prelude {
     #[doc(hidden)]
     #[cfg(feature = "bevy_reflect")]

crates/bevy_ecs/src/query/mod.rs

@@ -1,3 +1,14 @@
+//! Helper types for [`Query`](crate::system::Query).
+//!
+//! # Query filters
+//! Query filters restrict query results by filtering out entities that do not meet the criteria. The following is a full list of filters:
+//!
+//! - [`Added`]
+//! - [`Changed`]
+//! - [`With`]
+//! - [`Without`]
+//! - [`Or`]
+
 mod access;
 mod fetch;
 mod filter;

crates/bevy_ecs/src/reflect.rs

@@ -1,3 +1,5 @@
+//! Types that enable reflection support.
+
 pub use crate::change_detection::ReflectMut;
 use crate::{
     component::Component,