From 5854c35d674264366bc80ac9a65101340f057336 Mon Sep 17 00:00:00 2001 From: Daniel Bearden Date: Sun, 2 Jan 2022 17:10:14 -0800 Subject: [PATCH 01/15] Add doc comment to define_label macro trait --- crates/bevy_utils/src/label.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/crates/bevy_utils/src/label.rs b/crates/bevy_utils/src/label.rs index ed759f6a59886..7728ef8b947df 100644 --- a/crates/bevy_utils/src/label.rs +++ b/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 { From 2fe3c1ea3e66a70bf34a9661774ad0cc862041c9 Mon Sep 17 00:00:00 2001 From: Daniel Bearden Date: Sun, 2 Jan 2022 21:06:20 -0800 Subject: [PATCH 02/15] Complete documentation of bevy_app crate Achieves 100% doc coverage for public items in the bevy_app crate. Also, fixes a couple of minor typos in other crates. --- crates/bevy_app/src/app.rs | 10 ++++++- crates/bevy_app/src/lib.rs | 1 + crates/bevy_app/src/plugin.rs | 15 ++++++++++ crates/bevy_app/src/plugin_group.rs | 35 ++++++++++++++++++++++++ crates/bevy_app/src/schedule_runner.rs | 12 +++++++- crates/bevy_dynamic_plugin/src/loader.rs | 2 +- examples/asset/custom_asset_io.rs | 2 +- 7 files changed, 73 insertions(+), 4 deletions(-) diff --git a/crates/bevy_app/src/app.rs b/crates/bevy_app/src/app.rs index a9788252802d5..f7b25c09eb7a4 100644 --- a/crates/bevy_app/src/app.rs +++ b/crates/bevy_app/src/app.rs @@ -14,7 +14,6 @@ use std::fmt::Debug; #[cfg(feature = "trace")] use bevy_utils::tracing::info_span; - bevy_utils::define_label!(AppLabel); #[allow(clippy::needless_doctest_main)] @@ -42,12 +41,18 @@ bevy_utils::define_label!(AppLabel); /// } /// ``` pub struct App { + /// Stores and exposes operations on [entities](bevy_ecs::world::Entity), [components](bevy_ecs::world::Component), resources, + /// and their associated metadata. pub world: World, + /// A [runner function](Self::set_runner) which is typically not configured manually, + /// but set by a Bevy integrated plugin. pub runner: Box, + /// A container of [`Stage`]s set to be run in a linear order. pub schedule: Schedule, sub_apps: HashMap, SubApp>, } +/// Each [`SubApp`] has its own [`Schedule`] and [`World`], enabling a separation of concerns. struct SubApp { app: App, runner: Box, @@ -73,10 +78,12 @@ impl Default for App { } impl App { + /// Creates a new [`App`]. pub fn new() -> App { App::default() } + /// Creates a new empty [`App`]. pub fn empty() -> App { Self { world: Default::default(), @@ -837,6 +844,7 @@ impl App { self } + /// Inserts a "sub app" to this [App]. pub fn add_sub_app( &mut self, label: impl AppLabel, diff --git a/crates/bevy_app/src/lib.rs b/crates/bevy_app/src/lib.rs index c54d79d90f6ec..a2514d8c94728 100644 --- a/crates/bevy_app/src/lib.rs +++ b/crates/bevy_app/src/lib.rs @@ -16,6 +16,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}; diff --git a/crates/bevy_app/src/plugin.rs b/crates/bevy_app/src/plugin.rs index c1e791b1e08dd..b31ef1a7e104b 100644 --- a/crates/bevy_app/src/plugin.rs +++ b/crates/bevy_app/src/plugin.rs @@ -6,10 +6,25 @@ 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 an [`App`] + /// + /// # Examples + /// ``` + /// # struct MyPluginResource; + /// # fn my_plugin_system(); + /// + /// fn build(&self, app: &mut App){ + /// app.add_startup_system(my_plugin_system) + /// app.init_resource(MyPluginResource); + /// } + /// ``` fn build(&self, app: &mut App); + /// Configures a name for the [`Plugin`]. Primarily for debugging. fn name(&self) -> &str { std::any::type_name::() } } +/// 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; diff --git a/crates/bevy_app/src/plugin_group.rs b/crates/bevy_app/src/plugin_group.rs index 6bb41483bba89..692867f5d7f48 100644 --- a/crates/bevy_app/src/plugin_group.rs +++ b/crates/bevy_app/src/plugin_group.rs @@ -2,7 +2,17 @@ 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. + /// + /// # Examples + /// ``` + /// fn build(&mut self, group: &mut PluginGroupBuilder){ + /// group.add(Plugin1); + /// group.add(Plugin2); + /// } + /// ``` fn build(&mut self, group: &mut PluginGroupBuilder); } @@ -11,6 +21,9 @@ 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, @@ -18,6 +31,7 @@ pub struct PluginGroupBuilder { } impl PluginGroupBuilder { + /// Appends a [`Plugin`] to the [`PluginGroupBuilder`]. pub fn add(&mut self, plugin: T) -> &mut Self { self.order.push(TypeId::of::()); self.plugins.insert( @@ -30,6 +44,23 @@ impl PluginGroupBuilder { self } + /// Configures a [`Plugin`] to be built before another plugin. + /// + /// # Examples + /// From examples/asset/custom_asset_io.rs + /// ``` + /// App::new() + /// .add_plugins_with(DefaultPlugins, |group| { + /// // the custom asset io plugin must be inserted in-between the + /// // `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 asset server. In general, + /// // the AssetPlugin should still run so that other aspects of the + /// // asset system are initialized correctly. + /// group.add_before::(CustomAssetIoPlugin) + /// }) + /// ``` pub fn add_before(&mut self, plugin: T) -> &mut Self { let target_index = self .order @@ -54,6 +85,7 @@ impl PluginGroupBuilder { self } + /// Configures a [`Plugin`] to be built after another plugin. pub fn add_after(&mut self, plugin: T) -> &mut Self { let target_index = self .order @@ -78,6 +110,7 @@ impl PluginGroupBuilder { self } + /// Enables a [`Plugin`] pub fn enable(&mut self) -> &mut Self { let mut plugin_entry = self .plugins @@ -87,6 +120,7 @@ impl PluginGroupBuilder { self } + /// Disables a [`Plugin`] pub fn disable(&mut self) -> &mut Self { let mut plugin_entry = self .plugins @@ -96,6 +130,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) { diff --git a/crates/bevy_app/src/schedule_runner.rs b/crates/bevy_app/src/schedule_runner.rs index 526d4008f0344..83bf263f69008 100644 --- a/crates/bevy_app/src/schedule_runner.rs +++ b/crates/bevy_app/src/schedule_runner.rs @@ -14,7 +14,12 @@ use wasm_bindgen::{prelude::*, JsCast}; /// Determines the method used to run an [App]'s `Schedule` #[derive(Copy, Clone, Debug)] pub enum RunMode { - Loop { wait: Option }, + /// Indicates that the [App]'s schedule should run repeatedly. + Loop { + /// Minimum duration to wait after a schedule has completed before repeating. + wait: Option, + }, + /// Indicates that the [App]'s schedule should run only once. Once, } @@ -24,18 +29,23 @@ impl Default for RunMode { } } +/// Configuration information for [`ScheduleRunnerPlugin`]. #[derive(Copy, Clone, Default)] pub struct ScheduleRunnerSettings { + /// Determines whether the Schedule is run once or repeatedly. pub run_mode: RunMode, } impl ScheduleRunnerSettings { + /// Produces settings that tell the ScheduleRunner to run only once. pub fn run_once() -> Self { ScheduleRunnerSettings { run_mode: RunMode::Once, } } + /// Produces settings that tell the ScheduleRunner to wait for at least the provided `Duration` + /// before running again. pub fn run_loop(wait_duration: Duration) -> Self { ScheduleRunnerSettings { run_mode: RunMode::Loop { diff --git a/crates/bevy_dynamic_plugin/src/loader.rs b/crates/bevy_dynamic_plugin/src/loader.rs index 20c543944ccc2..6cc33e1bd996b 100644 --- a/crates/bevy_dynamic_plugin/src/loader.rs +++ b/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 diff --git a/examples/asset/custom_asset_io.rs b/examples/asset/custom_asset_io.rs index b47975e02894b..5ce725d1a592a 100644 --- a/examples/asset/custom_asset_io.rs +++ b/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::(CustomAssetIoPlugin) From 5868c64c6faa9066a7dd067281b75496256b2f72 Mon Sep 17 00:00:00 2001 From: Daniel Bearden Date: Sun, 2 Jan 2022 21:07:30 -0800 Subject: [PATCH 03/15] Add warn(missing_docs) --- crates/bevy_app/src/lib.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/crates/bevy_app/src/lib.rs b/crates/bevy_app/src/lib.rs index a2514d8c94728..a891c5957b786 100644 --- a/crates/bevy_app/src/lib.rs +++ b/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. From 0d1e64872b457a257adabb81c1034d63505f264e Mon Sep 17 00:00:00 2001 From: Daniel Bearden Date: Sun, 2 Jan 2022 21:42:20 -0800 Subject: [PATCH 04/15] Resolve issues with doc examples --- crates/bevy_app/src/app.rs | 2 +- crates/bevy_app/src/plugin_group.rs | 14 +++++++++++--- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/crates/bevy_app/src/app.rs b/crates/bevy_app/src/app.rs index f7b25c09eb7a4..826dc3327559c 100644 --- a/crates/bevy_app/src/app.rs +++ b/crates/bevy_app/src/app.rs @@ -41,7 +41,7 @@ bevy_utils::define_label!(AppLabel); /// } /// ``` pub struct App { - /// Stores and exposes operations on [entities](bevy_ecs::world::Entity), [components](bevy_ecs::world::Component), resources, + /// Stores and exposes operations on [entities](bevy_ecs::entity::Entity), [components](bevy_ecs::component::Component), resources, /// and their associated metadata. pub world: World, /// A [runner function](Self::set_runner) which is typically not configured manually, diff --git a/crates/bevy_app/src/plugin_group.rs b/crates/bevy_app/src/plugin_group.rs index 692867f5d7f48..763918a8e2fdf 100644 --- a/crates/bevy_app/src/plugin_group.rs +++ b/crates/bevy_app/src/plugin_group.rs @@ -8,9 +8,14 @@ pub trait PluginGroup { /// /// # Examples /// ``` - /// fn build(&mut self, group: &mut PluginGroupBuilder){ - /// group.add(Plugin1); - /// group.add(Plugin2); + /// # use bevy_app::plugin_group::PluginGroupBuilder; + /// # struct Plugin1; + /// # struct Plugin2; + /// impl PluginGroup for MyPluginGroup{ + /// fn build(&mut self, group: &mut PluginGroupBuilder){ + /// group.add(Plugin1); + /// group.add(Plugin2); + /// } /// } /// ``` fn build(&mut self, group: &mut PluginGroupBuilder); @@ -48,7 +53,10 @@ impl PluginGroupBuilder { /// /// # Examples /// From examples/asset/custom_asset_io.rs + /// /// ``` + /// # use bevy_internal::DefaultPlugins; + /// # struct CustomAssetIoPlugin; /// App::new() /// .add_plugins_with(DefaultPlugins, |group| { /// // the custom asset io plugin must be inserted in-between the From ee9c334a9f40c7a9772ea3527b0489c53c5af80d Mon Sep 17 00:00:00 2001 From: Daniel Bearden Date: Sun, 2 Jan 2022 22:00:07 -0800 Subject: [PATCH 05/15] Continue resolving issues with doc examples --- crates/bevy_app/src/plugin.rs | 12 ++++++++---- crates/bevy_app/src/plugin_group.rs | 7 ++++--- 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/crates/bevy_app/src/plugin.rs b/crates/bevy_app/src/plugin.rs index b31ef1a7e104b..a44dd0c454ef8 100644 --- a/crates/bevy_app/src/plugin.rs +++ b/crates/bevy_app/src/plugin.rs @@ -10,12 +10,16 @@ pub trait Plugin: Any + Send + Sync { /// /// # Examples /// ``` + /// # use bevy_app::App; + /// # struct MyPlugin; /// # struct MyPluginResource; - /// # fn my_plugin_system(); + /// # fn my_plugin_system(){} /// - /// fn build(&self, app: &mut App){ - /// app.add_startup_system(my_plugin_system) - /// app.init_resource(MyPluginResource); + /// impl Plugin for MyPlugin{ + /// fn build(&self, app: &mut App){ + /// app.add_startup_system(my_plugin_system); + /// app.init_resource(MyPluginResource); + /// } /// } /// ``` fn build(&self, app: &mut App); diff --git a/crates/bevy_app/src/plugin_group.rs b/crates/bevy_app/src/plugin_group.rs index 763918a8e2fdf..037eb882dc59c 100644 --- a/crates/bevy_app/src/plugin_group.rs +++ b/crates/bevy_app/src/plugin_group.rs @@ -8,9 +8,10 @@ pub trait PluginGroup { /// /// # Examples /// ``` - /// # use bevy_app::plugin_group::PluginGroupBuilder; + /// # use bevy_app::{PluginGroup,PluginGroupBuilder}; /// # struct Plugin1; /// # struct Plugin2; + /// # struct MyPluginGroup; /// impl PluginGroup for MyPluginGroup{ /// fn build(&mut self, group: &mut PluginGroupBuilder){ /// group.add(Plugin1); @@ -55,7 +56,7 @@ impl PluginGroupBuilder { /// From examples/asset/custom_asset_io.rs /// /// ``` - /// # use bevy_internal::DefaultPlugins; + /// # struct DefaultPlugins; /// # struct CustomAssetIoPlugin; /// App::new() /// .add_plugins_with(DefaultPlugins, |group| { @@ -66,7 +67,7 @@ impl PluginGroupBuilder { /// // 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::(CustomAssetIoPlugin) + /// group.add_before::(CustomAssetIoPlugin) /// }) /// ``` pub fn add_before(&mut self, plugin: T) -> &mut Self { From 42aaf7cf1b46629e1ae58874039add15694744ca Mon Sep 17 00:00:00 2001 From: Daniel Bearden Date: Sun, 2 Jan 2022 22:20:47 -0800 Subject: [PATCH 06/15] Forego doc examples for someone cleverer to write --- crates/bevy_app/src/plugin.rs | 15 ------------- crates/bevy_app/src/plugin_group.rs | 33 ----------------------------- 2 files changed, 48 deletions(-) diff --git a/crates/bevy_app/src/plugin.rs b/crates/bevy_app/src/plugin.rs index a44dd0c454ef8..0f5073b1674f6 100644 --- a/crates/bevy_app/src/plugin.rs +++ b/crates/bevy_app/src/plugin.rs @@ -7,21 +7,6 @@ use std::any::Any; /// a plugin, the plugin's [`Plugin::build`] function is run. pub trait Plugin: Any + Send + Sync { /// Configures an [`App`] - /// - /// # Examples - /// ``` - /// # use bevy_app::App; - /// # struct MyPlugin; - /// # struct MyPluginResource; - /// # fn my_plugin_system(){} - /// - /// impl Plugin for MyPlugin{ - /// fn build(&self, app: &mut App){ - /// app.add_startup_system(my_plugin_system); - /// app.init_resource(MyPluginResource); - /// } - /// } - /// ``` fn build(&self, app: &mut App); /// Configures a name for the [`Plugin`]. Primarily for debugging. fn name(&self) -> &str { diff --git a/crates/bevy_app/src/plugin_group.rs b/crates/bevy_app/src/plugin_group.rs index 037eb882dc59c..d579e6875d65c 100644 --- a/crates/bevy_app/src/plugin_group.rs +++ b/crates/bevy_app/src/plugin_group.rs @@ -5,20 +5,6 @@ use std::any::TypeId; /// Combines multiple [`Plugin`]s into a single unit. pub trait PluginGroup { /// Configures the [Plugin]s that are to be added. - /// - /// # Examples - /// ``` - /// # use bevy_app::{PluginGroup,PluginGroupBuilder}; - /// # struct Plugin1; - /// # struct Plugin2; - /// # struct MyPluginGroup; - /// impl PluginGroup for MyPluginGroup{ - /// fn build(&mut self, group: &mut PluginGroupBuilder){ - /// group.add(Plugin1); - /// group.add(Plugin2); - /// } - /// } - /// ``` fn build(&mut self, group: &mut PluginGroupBuilder); } @@ -51,25 +37,6 @@ impl PluginGroupBuilder { } /// Configures a [`Plugin`] to be built before another plugin. - /// - /// # Examples - /// From examples/asset/custom_asset_io.rs - /// - /// ``` - /// # struct DefaultPlugins; - /// # struct CustomAssetIoPlugin; - /// App::new() - /// .add_plugins_with(DefaultPlugins, |group| { - /// // the custom asset io plugin must be inserted in-between the - /// // `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 asset server. In general, - /// // the AssetPlugin should still run so that other aspects of the - /// // asset system are initialized correctly. - /// group.add_before::(CustomAssetIoPlugin) - /// }) - /// ``` pub fn add_before(&mut self, plugin: T) -> &mut Self { let target_index = self .order From acb2a5f33237e1634ece6e4c7eeb3b8449b89a76 Mon Sep 17 00:00:00 2001 From: Daniel Bearden Date: Tue, 4 Jan 2022 22:28:25 -0800 Subject: [PATCH 07/15] Apply suggestions from code review part 1 Co-authored-by: Alice Cecile --- crates/bevy_app/src/app.rs | 4 +++- crates/bevy_app/src/plugin.rs | 2 +- crates/bevy_app/src/plugin_group.rs | 4 ++-- crates/bevy_app/src/schedule_runner.rs | 8 ++++---- 4 files changed, 10 insertions(+), 8 deletions(-) diff --git a/crates/bevy_app/src/app.rs b/crates/bevy_app/src/app.rs index 826dc3327559c..c2753223839bd 100644 --- a/crates/bevy_app/src/app.rs +++ b/crates/bevy_app/src/app.rs @@ -844,7 +844,9 @@ impl App { self } - /// Inserts a "sub app" to this [App]. + /// Adds a "sub app" to this [`App`]. + /// + /// Sub apps are a largely experimental feature: each `SubApp` bas its own [`Schedule`] and [`World`]. pub fn add_sub_app( &mut self, label: impl AppLabel, diff --git a/crates/bevy_app/src/plugin.rs b/crates/bevy_app/src/plugin.rs index 0f5073b1674f6..f76b26393c740 100644 --- a/crates/bevy_app/src/plugin.rs +++ b/crates/bevy_app/src/plugin.rs @@ -6,7 +6,7 @@ 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 an [`App`] + /// Configures the [`App`] that this plugin is added to fn build(&self, app: &mut App); /// Configures a name for the [`Plugin`]. Primarily for debugging. fn name(&self) -> &str { diff --git a/crates/bevy_app/src/plugin_group.rs b/crates/bevy_app/src/plugin_group.rs index d579e6875d65c..294359b7eda82 100644 --- a/crates/bevy_app/src/plugin_group.rs +++ b/crates/bevy_app/src/plugin_group.rs @@ -4,7 +4,7 @@ use std::any::TypeId; /// Combines multiple [`Plugin`]s into a single unit. pub trait PluginGroup { - /// Configures the [Plugin]s that are to be added. + /// Configures the [`Plugin`]s that are to be added. fn build(&mut self, group: &mut PluginGroupBuilder); } @@ -96,7 +96,7 @@ impl PluginGroupBuilder { self } - /// Disables a [`Plugin`] + /// Disables a [`Plugin`], preventing it from being add to the `App` with the rest of the [`PluginGroup`]. pub fn disable(&mut self) -> &mut Self { let mut plugin_entry = self .plugins diff --git a/crates/bevy_app/src/schedule_runner.rs b/crates/bevy_app/src/schedule_runner.rs index 83bf263f69008..decb202aa05be 100644 --- a/crates/bevy_app/src/schedule_runner.rs +++ b/crates/bevy_app/src/schedule_runner.rs @@ -14,12 +14,12 @@ use wasm_bindgen::{prelude::*, JsCast}; /// Determines the method used to run an [App]'s `Schedule` #[derive(Copy, Clone, Debug)] pub enum RunMode { - /// Indicates that the [App]'s schedule should run repeatedly. + /// Indicates that the [`App`]'s schedule should run repeatedly. Loop { - /// Minimum duration to wait after a schedule has completed before repeating. + /// Minimum [`Duration`] to wait after a schedule has completed before repeating. wait: Option, }, - /// Indicates that the [App]'s schedule should run only once. + /// Indicates that the [`App`]'s schedule should run only once. Once, } @@ -32,7 +32,7 @@ impl Default for RunMode { /// Configuration information for [`ScheduleRunnerPlugin`]. #[derive(Copy, Clone, Default)] pub struct ScheduleRunnerSettings { - /// Determines whether the Schedule is run once or repeatedly. + /// Determines whether the [`Schedule`] is run once or repeatedly. pub run_mode: RunMode, } From 38461aa7ffa9a8656087763e82afb9afa767aabd Mon Sep 17 00:00:00 2001 From: Daniel Bearden Date: Wed, 5 Jan 2022 00:12:35 -0800 Subject: [PATCH 08/15] Apply suggestions from code review part 2 --- crates/bevy_app/src/app.rs | 20 +++++++++++++------- crates/bevy_app/src/schedule_runner.rs | 8 ++++---- 2 files changed, 17 insertions(+), 11 deletions(-) diff --git a/crates/bevy_app/src/app.rs b/crates/bevy_app/src/app.rs index 826dc3327559c..b6f17516a9de5 100644 --- a/crates/bevy_app/src/app.rs +++ b/crates/bevy_app/src/app.rs @@ -21,7 +21,7 @@ bevy_utils::define_label!(AppLabel); /// /// 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 +/// [runner function](Self::set_runner), which by default executes the App schedule /// once. Apps are constructed with the builder pattern. /// /// ## Example @@ -41,11 +41,15 @@ bevy_utils::define_label!(AppLabel); /// } /// ``` pub struct App { - /// Stores and exposes operations on [entities](bevy_ecs::entity::Entity), [components](bevy_ecs::component::Component), resources, - /// and their associated metadata. + /// 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`]s and [`Schedule`]s are needed, you can use [`SubApp`]s. pub world: World, - /// A [runner function](Self::set_runner) which is typically not configured manually, - /// but set by a Bevy integrated plugin. + /// 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, /// A container of [`Stage`]s set to be run in a linear order. pub schedule: Schedule, @@ -78,12 +82,14 @@ impl Default for App { } impl App { - /// Creates a new [`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`]. + /// 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(), diff --git a/crates/bevy_app/src/schedule_runner.rs b/crates/bevy_app/src/schedule_runner.rs index 83bf263f69008..01b38cea10a62 100644 --- a/crates/bevy_app/src/schedule_runner.rs +++ b/crates/bevy_app/src/schedule_runner.rs @@ -11,12 +11,13 @@ 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 { /// 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, }, /// Indicates that the [App]'s schedule should run only once. @@ -37,15 +38,14 @@ pub struct ScheduleRunnerSettings { } impl ScheduleRunnerSettings { - /// Produces settings that tell the ScheduleRunner to run only once. + /// [`RunMode::Once`] pub fn run_once() -> Self { ScheduleRunnerSettings { run_mode: RunMode::Once, } } - /// Produces settings that tell the ScheduleRunner to wait for at least the provided `Duration` - /// before running again. + /// [`RunMode::Loop`] pub fn run_loop(wait_duration: Duration) -> Self { ScheduleRunnerSettings { run_mode: RunMode::Loop { From 32e1a77828483c5a1b80aea2fc3bec409a3a8414 Mon Sep 17 00:00:00 2001 From: Daniel Bearden Date: Wed, 5 Jan 2022 00:29:47 -0800 Subject: [PATCH 09/15] Run cargo fmt --- crates/bevy_app/src/app.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/bevy_app/src/app.rs b/crates/bevy_app/src/app.rs index 35c955bdeda9a..5b8ee5c15c9e3 100644 --- a/crates/bevy_app/src/app.rs +++ b/crates/bevy_app/src/app.rs @@ -851,8 +851,8 @@ impl App { } /// Adds a "sub app" to this [`App`]. - /// - /// Sub apps are a largely experimental feature: each `SubApp` bas its own [`Schedule`] and [`World`]. + /// + /// Sub apps are a largely experimental feature: each `SubApp` bas its own [`Schedule`] and [`World`]. pub fn add_sub_app( &mut self, label: impl AppLabel, From 1c1ee8e0b30bd129989c72f3563d65f2c32b0316 Mon Sep 17 00:00:00 2001 From: Daniel Bearden Date: Wed, 5 Jan 2022 00:57:44 -0800 Subject: [PATCH 10/15] Correct doc errors --- crates/bevy_app/src/app.rs | 2 +- crates/bevy_app/src/schedule_runner.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/bevy_app/src/app.rs b/crates/bevy_app/src/app.rs index 5b8ee5c15c9e3..5b2b505c571dd 100644 --- a/crates/bevy_app/src/app.rs +++ b/crates/bevy_app/src/app.rs @@ -44,7 +44,7 @@ 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`]s and [`Schedule`]s are needed, you can use [`SubApp`]s. + /// If additional separate [`World`]s and [`Schedule`]s are needed, you can use `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`]. diff --git a/crates/bevy_app/src/schedule_runner.rs b/crates/bevy_app/src/schedule_runner.rs index 19754b1d4b9ec..3227826f70d06 100644 --- a/crates/bevy_app/src/schedule_runner.rs +++ b/crates/bevy_app/src/schedule_runner.rs @@ -33,7 +33,7 @@ impl Default for RunMode { /// Configuration information for [`ScheduleRunnerPlugin`]. #[derive(Copy, Clone, Default)] pub struct ScheduleRunnerSettings { - /// Determines whether the [`Schedule`] is run once or repeatedly. + /// Determines whether the [`Schedule`](bevy_ecs::schedule::Schedule) is run once or repeatedly. pub run_mode: RunMode, } From d8200fbdb4c9fe59086d8cd64c783ca20b7a4671 Mon Sep 17 00:00:00 2001 From: Daniel Bearden Date: Wed, 5 Jan 2022 09:17:49 -0800 Subject: [PATCH 11/15] Update crates/bevy_app/src/app.rs Co-authored-by: Alice Cecile --- crates/bevy_app/src/app.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_app/src/app.rs b/crates/bevy_app/src/app.rs index 5b2b505c571dd..0acf2112baf79 100644 --- a/crates/bevy_app/src/app.rs +++ b/crates/bevy_app/src/app.rs @@ -44,7 +44,7 @@ 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`]s and [`Schedule`]s are needed, you can use `sub_app`s. + /// If additional separate [`World`]-[`Schedule`] pairs are needed, you can use `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`]. From 1e0876a9b22fcb46aafa72b38d3d8b5588161ba5 Mon Sep 17 00:00:00 2001 From: Daniel Bearden Date: Wed, 5 Jan 2022 22:46:39 -0800 Subject: [PATCH 12/15] Futher doc additions and corrections --- crates/bevy_app/src/app.rs | 7 ++++--- crates/bevy_app/src/plugin.rs | 2 +- crates/bevy_app/src/plugin_group.rs | 11 +++++++---- 3 files changed, 12 insertions(+), 8 deletions(-) diff --git a/crates/bevy_app/src/app.rs b/crates/bevy_app/src/app.rs index 5b2b505c571dd..7460e9f768cac 100644 --- a/crates/bevy_app/src/app.rs +++ b/crates/bevy_app/src/app.rs @@ -21,8 +21,9 @@ bevy_utils::define_label!(AppLabel); /// /// Bundles together the necessary elements, like [`World`] and [`Schedule`], to create /// an ECS-based application. It also stores a pointer to a -/// [runner function](Self::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: @@ -852,7 +853,7 @@ impl App { /// Adds a "sub app" to this [`App`]. /// - /// Sub apps are a largely experimental feature: each `SubApp` bas its own [`Schedule`] and [`World`]. + /// 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, diff --git a/crates/bevy_app/src/plugin.rs b/crates/bevy_app/src/plugin.rs index f76b26393c740..4f00625fb55a2 100644 --- a/crates/bevy_app/src/plugin.rs +++ b/crates/bevy_app/src/plugin.rs @@ -6,7 +6,7 @@ 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`] that this plugin is added to + /// 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 { diff --git a/crates/bevy_app/src/plugin_group.rs b/crates/bevy_app/src/plugin_group.rs index 294359b7eda82..aecb3dd05acda 100644 --- a/crates/bevy_app/src/plugin_group.rs +++ b/crates/bevy_app/src/plugin_group.rs @@ -14,8 +14,8 @@ struct PluginEntry { } /// 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. +/// 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, @@ -87,6 +87,9 @@ impl PluginGroupBuilder { } /// 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(&mut self) -> &mut Self { let mut plugin_entry = self .plugins @@ -96,7 +99,7 @@ impl PluginGroupBuilder { self } - /// Disables a [`Plugin`], preventing it from being add to the `App` with the rest of the [`PluginGroup`]. + /// Disables a [`Plugin`], preventing it from being added to the `App` with the rest of the [`PluginGroup`]. pub fn disable(&mut self) -> &mut Self { let mut plugin_entry = self .plugins @@ -106,7 +109,7 @@ impl PluginGroupBuilder { self } - /// Consumes the [`PluginGroupBuilder`] and [builds](Plugin::build) the contained [Plugin]s. + /// 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) { From 248f3087789f7adc4d3b340e6076807605325fe4 Mon Sep 17 00:00:00 2001 From: Daniel Bearden Date: Thu, 6 Jan 2022 09:21:29 -0800 Subject: [PATCH 13/15] Update crates/bevy_app/src/app.rs Co-authored-by: Pascal Hertleif --- crates/bevy_app/src/app.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_app/src/app.rs b/crates/bevy_app/src/app.rs index e26c3af25f15b..75882fcbd5d21 100644 --- a/crates/bevy_app/src/app.rs +++ b/crates/bevy_app/src/app.rs @@ -45,7 +45,7 @@ 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`s. + /// 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`]. From dfb93883b1ea33aef27d1ea73d030e3057627718 Mon Sep 17 00:00:00 2001 From: Daniel Bearden Date: Thu, 6 Jan 2022 09:21:51 -0800 Subject: [PATCH 14/15] Update crates/bevy_app/src/app.rs Co-authored-by: Pascal Hertleif --- crates/bevy_app/src/app.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/crates/bevy_app/src/app.rs b/crates/bevy_app/src/app.rs index 75882fcbd5d21..64e78db661212 100644 --- a/crates/bevy_app/src/app.rs +++ b/crates/bevy_app/src/app.rs @@ -90,6 +90,7 @@ impl App { } /// 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 { From bf54106db51fe6cec4800c0472b90f2026eaf5df Mon Sep 17 00:00:00 2001 From: Daniel Bearden Date: Thu, 6 Jan 2022 09:22:06 -0800 Subject: [PATCH 15/15] Update crates/bevy_app/src/app.rs Co-authored-by: Pascal Hertleif --- crates/bevy_app/src/app.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_app/src/app.rs b/crates/bevy_app/src/app.rs index 64e78db661212..32007fec29c8b 100644 --- a/crates/bevy_app/src/app.rs +++ b/crates/bevy_app/src/app.rs @@ -50,7 +50,7 @@ pub struct App { /// 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). + /// See `bevy::winit::WinitPlugin` and [`ScheduleRunnerPlugin`](crate::schedule_runner::ScheduleRunnerPlugin). pub runner: Box, /// A container of [`Stage`]s set to be run in a linear order. pub schedule: Schedule,