From 6e44d8a2516eac6742f402b8651b906aa63768e1 Mon Sep 17 00:00:00 2001
From: Stephen Martindale <stephenmartindale@users.noreply.github.com>
Date: Tue, 24 Jan 2023 05:25:03 +0000
Subject: [PATCH] Docs: DefaultPlugins vs. MinimalPlugins and
 ScheduleRunnerPlugin (#7226)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

# Objective

The naming of the two plugin groups `DefaultPlugins` and `MinimalPlugins` suggests that one is a super-set of the other but this is not the case. Instead, the two plugin groups are intended for very different purposes.

Closes: https://github.com/bevyengine/bevy/issues/7173

## Solution

This merge request adds doc. comments that compensate for this and try save the user from confusion.

1. `DefaultPlugins` and `MinimalPlugins` intentions are described.
2. A strong emphasis on embracing `DefaultPlugins` as a whole but controlling what it contains with *Cargo* *features* is added – this is because the ordering in `DefaultPlugins` appears to be important so preventing users with "minimalist" foibles (That's Me!) from recreating the code seems worthwhile.
3. Notes are added explaining the confusing fact that `MinimalPlugins` contains `ScheduleRunnerPlugin` (which is very "important"-sounding) but `DefaultPlugins` does not.
---
 crates/bevy_app/src/schedule_runner.rs      | 10 ++++++++++
 crates/bevy_internal/src/default_plugins.rs | 21 +++++++++++++++++----
 2 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/crates/bevy_app/src/schedule_runner.rs b/crates/bevy_app/src/schedule_runner.rs
index 04535c045dd9d..28d39baffd2ff 100644
--- a/crates/bevy_app/src/schedule_runner.rs
+++ b/crates/bevy_app/src/schedule_runner.rs
@@ -61,6 +61,16 @@ impl ScheduleRunnerSettings {
 
 /// Configures an [`App`] to run its [`Schedule`](bevy_ecs::schedule::Schedule) according to a given
 /// [`RunMode`].
+///
+/// [`ScheduleRunnerPlugin`] is included in the
+/// [`MinimalPlugins`](https://docs.rs/bevy/latest/bevy/struct.MinimalPlugins.html) plugin group.
+///
+/// [`ScheduleRunnerPlugin`] is *not* included in the
+/// [`DefaultPlugins`](https://docs.rs/bevy/latest/bevy/struct.DefaultPlugins.html) plugin group
+/// which assumes that the [`Schedule`](bevy_ecs::schedule::Schedule) will be executed by other means:
+/// typically, the `winit` event loop
+/// (see [`WinitPlugin`](https://docs.rs/bevy/latest/bevy/winit/struct.WinitPlugin.html))
+/// executes the schedule making [`ScheduleRunnerPlugin`] unnecessary.
 #[derive(Default)]
 pub struct ScheduleRunnerPlugin;
 
diff --git a/crates/bevy_internal/src/default_plugins.rs b/crates/bevy_internal/src/default_plugins.rs
index 7bd49c761dc05..6860267ad99b5 100644
--- a/crates/bevy_internal/src/default_plugins.rs
+++ b/crates/bevy_internal/src/default_plugins.rs
@@ -1,6 +1,6 @@
 use bevy_app::{PluginGroup, PluginGroupBuilder};
 
-/// This plugin group will add all the default plugins:
+/// This plugin group will add all the default plugins for a *Bevy* application:
 /// * [`LogPlugin`](crate::log::LogPlugin)
 /// * [`TaskPoolPlugin`](crate::core::TaskPoolPlugin)
 /// * [`TypeRegistrationPlugin`](crate::core::TypeRegistrationPlugin)
@@ -23,7 +23,13 @@ use bevy_app::{PluginGroup, PluginGroupBuilder};
 /// * [`GltfPlugin`](crate::gltf::GltfPlugin) - with feature `bevy_gltf`
 /// * [`WinitPlugin`](crate::winit::WinitPlugin) - with feature `bevy_winit`
 ///
-/// See also [`MinimalPlugins`] for a slimmed down option
+/// [`DefaultPlugins`] obeys *Cargo* *feature* flags. Users may exert control over this plugin group
+/// by disabling `default-features` in their `Cargo.toml` and enabling only those features
+/// that they wish to use.
+///
+/// [`DefaultPlugins`] contains all the plugins typically required to build
+/// a *Bevy* application which includes a *window* and presentation components.
+/// For *headless* cases – without a *window* or presentation, see [`MinimalPlugins`].
 pub struct DefaultPlugins;
 
 impl PluginGroup for DefaultPlugins {
@@ -127,14 +133,21 @@ impl PluginGroup for DefaultPlugins {
     }
 }
 
-/// Minimal plugin group that will add the following plugins:
+/// This plugin group will add the minimal plugins for a *Bevy* application:
 /// * [`TaskPoolPlugin`](crate::core::TaskPoolPlugin)
 /// * [`TypeRegistrationPlugin`](crate::core::TypeRegistrationPlugin)
 /// * [`FrameCountPlugin`](crate::core::FrameCountPlugin)
 /// * [`TimePlugin`](crate::time::TimePlugin)
 /// * [`ScheduleRunnerPlugin`](crate::app::ScheduleRunnerPlugin)
 ///
-/// See also [`DefaultPlugins`] for a more complete set of plugins
+/// This group of plugins is intended for use for minimal, *headless* programs –
+/// see the [*Bevy* *headless* example](https://github.com/bevyengine/bevy/blob/main/examples/app/headless.rs)
+/// – and includes a [schedule runner (`ScheduleRunnerPlugin`)](crate::app::ScheduleRunnerPlugin)
+/// to provide functionality that would otherwise be driven by a windowed application's
+/// *event loop* or *message loop*.
+///
+/// Windowed applications that wish to use a reduced set of plugins should consider the
+/// [`DefaultPlugins`] plugin group which can be controlled with *Cargo* *feature* flags.
 pub struct MinimalPlugins;
 
 impl PluginGroup for MinimalPlugins {