[Merged by Bors] - Bevy app docs

crates/bevy_app/src/app.rs

@@ -14,16 +14,16 @@ use std::fmt::Debug;
 
 #[cfg(feature = "trace")]
 use bevy_utils::tracing::info_span;
-
 bevy_utils::define_label!(AppLabel);
 
 #[allow(clippy::needless_doctest_main)]
 /// Containers of app logic and data
 ///
 /// Bundles together the necessary elements, like [`World`] and [`Schedule`], to create
 /// an ECS-based application. It also stores a pointer to a
-/// [runner function](App::set_runner), which by default executes the App schedule
-/// once. Apps are constructed with the builder pattern.
+/// [runner function](Self::set_runner). The runner is responsible for managing the application's
+/// event loop and applying the [`Schedule`] to the [`World`] to drive application logic.
+/// Apps are constructed with the builder pattern.
 ///
 /// ## Example
 /// Here is a simple "Hello World" Bevy app:
@@ -42,12 +42,22 @@ bevy_utils::define_label!(AppLabel);
 /// }
 /// ```
 pub struct App {
+ /// The main ECS [`World`] of the [`App`].
+ /// This stores and provides access to all the main data of the application.
+ /// The systems of the [`App`] will run using this [`World`].
+ /// If additional separate [`World`]-[`Schedule`] pairs are needed, you can use [`sub_app`][App::add_sub_app]s.
  pub world: World,
+ /// The [runner function](Self::set_runner) is primarily responsible for managing
+ /// the application's event loop and advancing the [`Schedule`].
+ /// Typically, it is not configured manually, but set by one of Bevy's built-in plugins.
+ /// See `bevy::winit::WinitPlugin` and [`ScheduleRunnerPlugin`](crate::schedule_runner::ScheduleRunnerPlugin).
  pub runner: Box<dyn Fn(App)>,
+ /// A container of [`Stage`]s set to be run in a linear order.
  pub schedule: Schedule,
  sub_apps: HashMap<Box<dyn AppLabel>, SubApp>,
 }
 
+/// Each [`SubApp`] has its own [`Schedule`] and [`World`], enabling a separation of concerns.
 struct SubApp {
  app: App,
  runner: Box<dyn Fn(&mut World, &mut App)>,
@@ -73,10 +83,15 @@ impl Default for App {
 }
 
 impl App {
+ /// Creates a new [`App`] with some default structure to enable core engine features.
+ /// This is the preferred constructor for most use cases.
  pub fn new() -> App {
  App::default()
  }
 
+ /// Creates a new empty [`App`] with minimal default configuration.
+ ///
+ /// This constructor should be used if you wish to provide a custom schedule, exit handling, cleanup, etc.
  pub fn empty() -> App {
  Self {
  world: Default::default(),
@@ -837,6 +852,9 @@ impl App {
  self
  }
 
+ /// Adds a "sub app" to this [`App`].
+ ///
+ /// Sub apps are a largely experimental feature: each `SubApp` has its own [`Schedule`] and [`World`].
  pub fn add_sub_app(
  &mut self,
  label: impl AppLabel,

crates/bevy_app/src/lib.rs

@@ -1,3 +1,4 @@
+#![warn(missing_docs)]
 //! This crate is about everything concerning the highest-level, application layer of a Bevy
 //! app.
 
@@ -16,6 +17,7 @@ pub use plugin::*;
 pub use plugin_group::*;
 pub use schedule_runner::*;
 
+#[allow(missing_docs)]
 pub mod prelude {
  #[doc(hidden)]
  pub use crate::{app::App, CoreStage, DynamicPlugin, Plugin, PluginGroup, StartupStage};

crates/bevy_app/src/plugin.rs

@@ -6,10 +6,14 @@ use std::any::Any;
 /// Plugins configure an [`App`](crate::App). When an [`App`](crate::App) registers
 /// a plugin, the plugin's [`Plugin::build`] function is run.
 pub trait Plugin: Any + Send + Sync {
+ /// Configures the [`App`] to which this plugin is added.
  fn build(&self, app: &mut App);
+ /// Configures a name for the [`Plugin`]. Primarily for debugging.
  fn name(&self) -> &str {
  std::any::type_name::<Self>()
  }
 }
 
+/// Type representing an unsafe function that returns a mutable pointer to a [`Plugin`].
+/// Used for dynamically loading plugins. See bevy_dynamic_plugin/src/loader.rs#dynamically_load_plugin
 pub type CreatePlugin = unsafe fn() -> *mut dyn Plugin;

crates/bevy_app/src/plugin_group.rs

@@ -2,7 +2,9 @@ use crate::{App, Plugin};
 use bevy_utils::{tracing::debug, HashMap};
 use std::any::TypeId;
 
+/// Combines multiple [`Plugin`]s into a single unit.
 pub trait PluginGroup {
+ /// Configures the [`Plugin`]s that are to be added.
  fn build(&mut self, group: &mut PluginGroupBuilder);
 }
 
@@ -11,13 +13,17 @@ struct PluginEntry {
  enabled: bool,
 }
 
+/// Facilitates the creation and configuration of a [`PluginGroup`].
+/// Provides a build ordering to ensure that [`Plugin`]s which produce/require a resource
+/// are built before/after dependent/depending [`Plugin`]s.
 #[derive(Default)]
 pub struct PluginGroupBuilder {
  plugins: HashMap<TypeId, PluginEntry>,
  order: Vec<TypeId>,
 }
 
 impl PluginGroupBuilder {
+ /// Appends a [`Plugin`] to the [`PluginGroupBuilder`].
  pub fn add<T: Plugin>(&mut self, plugin: T) -> &mut Self {
  self.order.push(TypeId::of::<T>());
  self.plugins.insert(
@@ -30,6 +36,7 @@ impl PluginGroupBuilder {
  self
  }
 
+ /// Configures a [`Plugin`] to be built before another plugin.
  pub fn add_before<Target: Plugin, T: Plugin>(&mut self, plugin: T) -> &mut Self {
  let target_index = self
  .order
@@ -54,6 +61,7 @@ impl PluginGroupBuilder {
  self
  }
 
+ /// Configures a [`Plugin`] to be built after another plugin.
  pub fn add_after<Target: Plugin, T: Plugin>(&mut self, plugin: T) -> &mut Self {
  let target_index = self
  .order
@@ -78,6 +86,10 @@ impl PluginGroupBuilder {
  self
  }
 
+ /// Enables a [`Plugin`]
+ ///
+ /// [`Plugin`]s within a [`PluginGroup`] are enabled by default. This function is used to
+ /// opt back in to a [`Plugin`] after [disabling](Self::disable) it.
  pub fn enable<T: Plugin>(&mut self) -> &mut Self {
  let mut plugin_entry = self
  .plugins
@@ -87,6 +99,7 @@ impl PluginGroupBuilder {
  self
  }
 
+ /// Disables a [`Plugin`], preventing it from being added to the `App` with the rest of the [`PluginGroup`].
  pub fn disable<T: Plugin>(&mut self) -> &mut Self {
  let mut plugin_entry = self
  .plugins
@@ -96,6 +109,7 @@ impl PluginGroupBuilder {
  self
  }
 
+ /// Consumes the [`PluginGroupBuilder`] and [builds](Plugin::build) the contained [`Plugin`]s.
  pub fn finish(self, app: &mut App) {
  for ty in self.order.iter() {
  if let Some(entry) = self.plugins.get(ty) {

crates/bevy_app/src/schedule_runner.rs

@@ -11,10 +11,16 @@ use std::{cell::RefCell, rc::Rc};
 #[cfg(target_arch = "wasm32")]
 use wasm_bindgen::{prelude::*, JsCast};
 
-/// Determines the method used to run an [App]'s `Schedule`
+/// Determines the method used to run an [App]'s  [`Schedule`](bevy_ecs::schedule::Schedule).
 #[derive(Copy, Clone, Debug)]
 pub enum RunMode {
- Loop { wait: Option<Duration> },
+ /// Indicates that the [`App`]'s schedule should run repeatedly.
+ Loop {
+ /// Minimum duration to wait after a schedule has completed before repeating.
+ /// A value of [`None`] will not wait.
+ wait: Option<Duration>,
+ },
+ /// Indicates that the [`App`]'s schedule should run only once.
  Once,
 }
 
@@ -24,18 +30,22 @@ impl Default for RunMode {
  }
 }
 
+/// Configuration information for [`ScheduleRunnerPlugin`].
 #[derive(Copy, Clone, Default)]
 pub struct ScheduleRunnerSettings {
+ /// Determines whether the [`Schedule`](bevy_ecs::schedule::Schedule) is run once or repeatedly.
  pub run_mode: RunMode,
 }
 
 impl ScheduleRunnerSettings {
+ /// [`RunMode::Once`]
  pub fn run_once() -> Self {
  ScheduleRunnerSettings {
  run_mode: RunMode::Once,
  }
  }
 
+ /// [`RunMode::Loop`] 
  pub fn run_loop(wait_duration: Duration) -> Self {
  ScheduleRunnerSettings {
  run_mode: RunMode::Loop {

crates/bevy_dynamic_plugin/src/loader.rs

@@ -2,7 +2,7 @@ use libloading::{Library, Symbol};
 
 use bevy_app::{App, CreatePlugin, Plugin};
 
-/// Dynamically links a plugin a the given path. The plugin must export a function with the
+/// Dynamically links a plugin at the given path. The plugin must export a function with the
 /// [`CreatePlugin`] signature named `_bevy_create_plugin`.
 ///
 /// # Safety

crates/bevy_utils/src/label.rs

@@ -58,6 +58,7 @@ where
 #[macro_export]
 macro_rules! define_label {
  ($label_trait_name:ident) => {
+ /// Defines a set of strongly-typed labels for a class of objects
  pub trait $label_trait_name:
  ::bevy_utils::label::DynHash + ::std::fmt::Debug + Send + Sync + 'static
  {

examples/asset/custom_asset_io.rs

@@ -80,7 +80,7 @@ fn main() {
  // `CorePlugin' and `AssetPlugin`. It needs to be after the
  // CorePlugin, so that the IO task pool has already been constructed.
  // And it must be before the `AssetPlugin` so that the asset plugin
- // doesn't create another instance of an assert server. In general,
+ // doesn't create another instance of an asset server. In general,
  // the AssetPlugin should still run so that other aspects of the
  // asset system are initialized correctly.
  group.add_before::<bevy::asset::AssetPlugin, _>(CustomAssetIoPlugin)