From ff3b0d0af3bef952dcf987c0fede656cdd7b8396 Mon Sep 17 00:00:00 2001
From: Daniel McNab <36049421+DJMcNab@users.noreply.github.com>
Date: Thu, 6 Jan 2022 23:05:23 +0000
Subject: [PATCH] Add suggested docs

---
 crates/bevy_window/src/lib.rs    |  5 +++++
 crates/bevy_window/src/system.rs | 18 +++++++++++++++++-
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/crates/bevy_window/src/lib.rs b/crates/bevy_window/src/lib.rs
index 45b43215745689..08749f62838494 100644
--- a/crates/bevy_window/src/lib.rs
+++ b/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,
 }
diff --git a/crates/bevy_window/src/system.rs b/crates/bevy_window/src/system.rs
index da264550ac305e..1ec6faa8a4f9e5 100644
--- a/crates/bevy_window/src/system.rs
+++ b/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);
     }