Improve bevy_ecs and bevy_app API docs where referenced by the new Be…

…vy Book (#2365)

## Objective

The upcoming Bevy Book makes many references to the API documentation of bevy.

Most references belong to the first two chapters of the Bevy Book:

- bevyengine/bevy-website#176
- bevyengine/bevy-website#182

This PR attempts to improve the documentation of `bevy_ecs` and `bevy_app` in order to help readers of the Book who want to delve deeper into technical details.

## Solution

- Add crate and level module documentation
- Document the most important items (basically those included in the preludes), with the following style, where applicable:
    - **Summary.** Short description of the item.
    - **Second paragraph.** Detailed description of the item, without going too much in the implementation.
    - **Code example(s).**
    - **Safety or panic notes.**

## Collaboration

Any kind of collaboration is welcome, especially corrections, wording, new ideas and guidelines on where the focus should be put in.

---

### Related issues

- Fixes #2246

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,27 @@
+//! Entity handling types.
+//!
+//! In Bevy ECS, there is no monolithic data structure for an entity. Instead, the [`Entity`]
+//! `struct` is just a *generational index* (a combination of an ID and a generation). Then,
+//! the `Entity` maps to the specific [`Component`s](crate::component::Component). This way,
+//! entities can have meaningful data attached 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 +60,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/reflect.rs

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