From 73ae6af6efc3e8e525e8068fa6f58bfd0d03cc8c Mon Sep 17 00:00:00 2001 From: Mika Date: Thu, 6 May 2021 02:26:54 +0000 Subject: [PATCH] Add inline documentation to bevy code (#1404) For review, first iteration of bevy code documentation. I can continue submitting docs every now and then for relevant parts. Some challenges I found: * plugins example had to be commented out, as adding bevy_internal (where plugins reside) would pull in too many dependencies Co-authored-by: Mika <1299457+blaind@users.noreply.github.com> Co-authored-by: Carter Anderson --- crates/bevy_app/Cargo.toml | 4 + crates/bevy_app/src/app_builder.rs | 205 ++++++++++++++++++++++++++++- 2 files changed, 207 insertions(+), 2 deletions(-) diff --git a/crates/bevy_app/Cargo.toml b/crates/bevy_app/Cargo.toml index ddb68b458e..c767c6783a 100644 --- a/crates/bevy_app/Cargo.toml +++ b/crates/bevy_app/Cargo.toml @@ -32,3 +32,7 @@ ron = { version = "0.6.2", optional = true } [target.'cfg(target_arch = "wasm32")'.dependencies] wasm-bindgen = { version = "0.2" } web-sys = { version = "0.3", features = [ "Window" ] } + +[dev-dependencies] +# bevy +bevy_log = { path = "../bevy_log", version = "0.5.0" } diff --git a/crates/bevy_app/src/app_builder.rs b/crates/bevy_app/src/app_builder.rs index c32f380607..58a2dbdd87 100644 --- a/crates/bevy_app/src/app_builder.rs +++ b/crates/bevy_app/src/app_builder.rs @@ -49,6 +49,22 @@ impl AppBuilder { } } + /// 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`]. + /// + /// ## Example + /// ``` + /// # use bevy_app::prelude::*; + /// # + /// App::build() + /// // all required plugin insertions, systems, etc inserted here + /// // finally, call: + /// .run(); + /// ``` pub fn run(&mut self) { let app = std::mem::take(&mut self.app); app.run(); @@ -138,6 +154,32 @@ 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`]. + /// + /// For adding a system that runs only at app startup, see [`AppBuilder::add_startup_system`]. + /// + /// ## Example + /// ``` + /// # use bevy_app::prelude::*; + /// # use bevy_ecs::prelude::*; + /// # + /// fn my_system(_commands: Commands) { + /// println!("My system, triggered once per frame"); + /// } + /// + /// App::build() + /// .add_system(my_system.system()); + /// ``` pub fn add_system(&mut self, system: impl Into) -> &mut Self { self.add_system_to_stage(CoreStage::Update, system) } @@ -166,6 +208,26 @@ 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). + /// + /// * 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`]. + /// + /// ## Example + /// ``` + /// # use bevy_app::prelude::*; + /// # use bevy_ecs::prelude::*; + /// # + /// fn my_startup_system(_commands: Commands) { + /// println!("My startup system"); + /// } + /// + /// App::build() + /// .add_startup_system(my_startup_system.system()); + /// ``` pub fn add_startup_system(&mut self, system: impl Into) -> &mut Self { self.add_startup_system_to_stage(StartupStage::Startup, system) } @@ -236,8 +298,24 @@ impl AppBuilder { .add_system_to_stage(CoreStage::First, Events::::update_system.system()) } - /// Inserts a resource to the current [App] and overwrites any resource previously added of the - /// same type. + /// Inserts a resource to the current [App] and overwrites any resource previously added of the same type. + /// + /// 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`]. + /// + /// ## Example + /// ``` + /// # use bevy_app::prelude::*; + /// # + /// struct MyCounter { + /// counter: usize, + /// } + /// + /// App::build() + /// .insert_resource(MyCounter { counter: 0 }); + /// ``` pub fn insert_resource(&mut self, resource: T) -> &mut Self where T: Component, @@ -246,6 +324,22 @@ impl AppBuilder { self } + /// Inserts a non-send resource to the app + /// + /// You usually want to use `insert_resource`, but there are some special cases when a resource must + /// be non-send. + /// + /// ## Example + /// ``` + /// # use bevy_app::prelude::*; + /// # + /// struct MyCounter { + /// counter: usize, + /// } + /// + /// App::build() + /// .insert_non_send_resource(MyCounter { counter: 0 }); + /// ``` pub fn insert_non_send_resource(&mut self, resource: T) -> &mut Self where T: 'static, @@ -254,6 +348,30 @@ impl AppBuilder { self } + /// Initialize a 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, `init_resource` does nothing. + /// + /// ## Example + /// ``` + /// # use bevy_app::prelude::*; + /// # + /// struct MyCounter { + /// counter: usize, + /// } + /// + /// impl Default for MyCounter { + /// fn default() -> MyCounter { + /// MyCounter { + /// counter: 100 + /// } + /// } + /// } + /// + /// App::build() + /// .init_resource::(); + /// ``` pub fn init_resource(&mut self) -> &mut Self where R: FromWorld + Send + Sync + 'static, @@ -280,11 +398,45 @@ impl AppBuilder { self } + /// Sets the main runner loop function for this Bevy App + /// + /// Usually the main loop is handled by Bevy integrated plugins ([`WinitPlugin`]), but + /// in some cases one might wish to implement their own main loop. + /// + /// This method sets the main loop function, overwriting a previous runner if any. + /// + /// ## Example + /// ``` + /// # use bevy_app::prelude::*; + /// # + /// fn my_runner(mut app: App) { + /// loop { + /// println!("In main loop"); + /// app.update(); + /// } + /// } + /// + /// App::build() + /// .set_runner(my_runner); + /// ``` pub fn set_runner(&mut self, run_fn: impl Fn(App) + 'static) -> &mut Self { self.app.runner = Box::new(run_fn); self } + /// Adds a single plugin + /// + /// One of Bevy's core principles is modularity. All Bevy engine features are implemented + /// as plugins. This includes internal features like the renderer. + /// + /// Bevy also provides a few sets of default plugins. See [`AppBuilder::add_plugins`]. + /// + /// ## Example + /// ``` + /// # use bevy_app::prelude::*; + /// # + /// App::build().add_plugin(bevy_log::LogPlugin::default()); + /// ``` pub fn add_plugin(&mut self, plugin: T) -> &mut Self where T: Plugin, @@ -294,6 +446,26 @@ impl AppBuilder { self } + /// Adds a group of plugins + /// + /// Bevy plugins can be grouped into a set of plugins. Bevy provides + /// built-in PluginGroups that provide core engine functionality. + /// + /// The plugin groups available by default are [`DefaultPlugins`] and [`MinimalPlugins`]. + /// + /// ## Example + /// ``` + /// # use bevy_app::{prelude::*, PluginGroupBuilder}; + /// # + /// # // Dummy created to avoid using bevy_internal, which pulls in to many dependencies. + /// # struct MinimalPlugins; + /// # impl PluginGroup for MinimalPlugins { + /// # fn build(&mut self, group: &mut PluginGroupBuilder){;} + /// # } + /// # + /// App::build() + /// .add_plugins(MinimalPlugins); + /// ``` pub fn add_plugins(&mut self, mut group: T) -> &mut Self { let mut plugin_group_builder = PluginGroupBuilder::default(); group.build(&mut plugin_group_builder); @@ -301,6 +473,35 @@ impl AppBuilder { self } + /// Adds a group of plugins with an initializer method + /// + /// Can be used to add a group of plugins, where the group is modified + /// before insertion into Bevy application. For example, you can add + /// extra plugins at a specific place in the plugin group, or deactivate + /// specific plugins while keeping the rest. + /// + /// ## Example + /// ``` + /// # use bevy_app::{prelude::*, PluginGroupBuilder}; + /// # + /// # // Dummies created to avoid using bevy_internal which pulls in to many dependencies. + /// # struct DefaultPlugins; + /// # impl PluginGroup for DefaultPlugins { + /// # fn build(&mut self, group: &mut PluginGroupBuilder){ + /// # group.add(bevy_log::LogPlugin::default()); + /// # } + /// # } + /// # + /// # struct MyOwnPlugin; + /// # impl Plugin for MyOwnPlugin { + /// # fn build(&self, app: &mut AppBuilder){;} + /// # } + /// # + /// App::build() + /// .add_plugins_with(DefaultPlugins, |group| { + /// group.add_before::(MyOwnPlugin) + /// }); + /// ``` pub fn add_plugins_with(&mut self, mut group: T, func: F) -> &mut Self where T: PluginGroup,