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 <[email protected]>
Co-authored-by: Carter Anderson <[email protected]>

Author: blaind

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" }

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<SystemDescriptor>) -> &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<SystemDescriptor>) -> &mut Self {
         self.add_startup_system_to_stage(StartupStage::Startup, system)
     }
@@ -236,8 +298,24 @@ impl AppBuilder {
             .add_system_to_stage(CoreStage::First, Events::<T>::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<T>(&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<T>(&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::<MyCounter>();
+    /// ```
     pub fn init_resource<R>(&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<T>(&mut self, plugin: T) -> &mut Self
     where
         T: Plugin,
@@ -294,13 +446,62 @@ 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<T: PluginGroup>(&mut self, mut group: T) -> &mut Self {
         let mut plugin_group_builder = PluginGroupBuilder::default();
         group.build(&mut plugin_group_builder);
         plugin_group_builder.finish(self);
         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::<bevy_log::LogPlugin, _>(MyOwnPlugin)
+    ///         });
+    /// ```
     pub fn add_plugins_with<T, F>(&mut self, mut group: T, func: F) -> &mut Self
     where
         T: PluginGroup,