Add suggested docs

Author: DJMcNab

crates/bevy_window/src/lib.rs

@@ -25,9 +25,14 @@ use bevy_app::{prelude::*, Events};
 pub struct WindowPlugin {
     pub add_primary_window: bool,
     /// Whether to close the app when there are no open windows.
+    /// If disabling this, consider ensuring that you send a [`bevy_app::AppExit`] event yourself
+    /// when the app should exit; otherwise you will create headless processes, which would be
+    /// surprising for your users.
+    ///
     /// This setting controls whether this plugin adds [`exit_on_all_closed`]
     pub exit_on_all_closed: bool,
     /// Whether to close windows when they are requested to be closed (i.e. when the close button is pressed)
+    ///
     /// This setting controls whether this plugin adds [`close_when_requested`]
     pub close_when_requested: bool,
 }

crates/bevy_window/src/system.rs

@@ -3,12 +3,23 @@ use bevy_app::{AppExit, EventReader, EventWriter};
 use bevy_ecs::prelude::*;
 use bevy_input::{keyboard::KeyCode, Input};
 
+/// Whether to exit the application when there are no open windows.
+///
+/// By default, this system is added by the [`crate::WindowPlugin`].
+/// To disable this behaviour, set `close_when_requested` (on the [`crate::WindowPlugin`]) to `false`.
+/// Please ensure that you read the caveats documented on that field.
+
 pub fn exit_on_all_closed(mut app_exit_events: EventWriter<AppExit>, windows: Res<Windows>) {
     if windows.iter().count() == 0 {
         app_exit_events.send(AppExit);
     }
 }
 
+/// Whether to close windows when they are requested to be closed (i.e. when the close button is pressed).
+/// Not adding this system (without replacement) will lead to the close button having no effect.
+///
+/// By default, this system is added by the [`crate::WindowPlugin`].
+/// To disable this behaviour, set `close_when_requested` (on the [`crate::WindowPlugin`]) to `false`
 pub fn close_when_requested(
     mut windows: ResMut<Windows>,
     mut closed: EventReader<WindowCloseRequested>,
@@ -18,13 +29,18 @@ pub fn close_when_requested(
     }
 }
 
+// TODO: Consider using the kbd tag here for escape: <kbd>esc</kbd>
+// Currently, it isn't rendered by vscode's hover markdown provider (and the contents are lost)
+/// Close the focused window whenever the escape key is pressed
+///
+/// This is useful for examples
 pub fn close_on_esc(
     mut focused: Local<Option<WindowId>>,
     mut focused_events: EventReader<WindowFocused>,
     mut windows: ResMut<Windows>,
     input: Res<Input<KeyCode>>,
 ) {
-    // Todo: Track this more generally
+    // TODO: Track this in e.g. a resource to ensure consistent behaviour across similar systems
     for event in focused_events.iter() {
         *focused = event.focused.then(|| event.id);
     }