Update docs

crates/bevy_window/src/event.rs

@@ -31,21 +31,24 @@ pub struct WindowCreated {
     pub id: WindowId,
 }
 
-/// An event that is sent whenever a close was requested for a window. For example: when the "close"
-/// button is pressed on a window.
+/// An event that is sent whenever the operating systems requests that a window
+/// be closed. This will be sent when the close button of the window is pressed.
 ///
-/// By default, these events are handled by closing the corresponding [`crate::Window`].
-/// To disable this behaviour, set `close_when_requested` on the [`crate::WindowPlugin`] to `false`
+/// If the default [`WindowPlugin`] is used, these events are handled
+/// by [closing] the corresponding [`Window`].  
+/// To disable this behaviour, set `close_when_requested` on the [`WindowPlugin`]
+/// to `false`.
+///
+/// [`WindowPlugin`]: crate::WindowPlugin
+/// [`Window`]: crate::Window
+/// [closing]: crate::Window::close
 #[derive(Debug, Clone)]
 pub struct WindowCloseRequested {
     pub id: WindowId,
 }
 
 /// An event that is sent whenever a window is closed.
-/// This will only be sent in response to the [`Window::close`] method.
-///
-/// By default, when no windows are open, the app will close.
-/// To disable this behaviour, set `exit_on_all_closed` on the [`crate::WindowPlugin`] to `false`
+/// This will be sent in response to the [`Window::close`] method.
 ///
 /// [`Window::close`]: crate::Window::close
 #[derive(Debug, Clone)]

crates/bevy_window/src/lib.rs

@@ -24,17 +24,22 @@ use bevy_app::prelude::*;
 use bevy_ecs::{event::Events, schedule::SystemLabel};
 
 pub struct WindowPlugin {
+    /// Whether to create a window when added.
+    /// Note that if there are no windows, by default
     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.
+    /// Whether to exit the app when there are no open windows.
+    /// If disabling this, ensure that you send the [`bevy_app::AppExit`]
+    /// event when the app should exit. If this does not occur, you will
+    /// create 'headless' processes (processes without windows), which may
+    /// surprise your users.
     ///
-    /// This setting controls whether this plugin adds [`exit_on_all_closed`]
+    /// If true, this plugin will add [`exit_on_all_closed`] to [`CoreStage::Update`].
     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`]
+    /// Not adding this system (without replacement) will lead to the close button having no effect.
+    ///
+    /// If true, this plugin will add [`close_when_requested`] to [`CoreStage::Update`].
     pub close_when_requested: bool,
 }
 

crates/bevy_window/src/system.rs

@@ -4,20 +4,18 @@ use bevy_app::AppExit;
 use bevy_ecs::prelude::*;
 use bevy_input::{keyboard::KeyCode, Input};
 
-/// Whether to exit the application when there are no open windows.
+/// Exit the application when there are no open windows.
 ///
-/// By default, this system is added by the [`crate::WindowPlugin`].
+/// This system is added by the [`crate::WindowPlugin`] in the default configuration.
 /// 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.
-
+/// nsure 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.
+/// Whether to close windows when they are requested to be closed (e.g.  when the close button is pressed).
 ///
 /// By default, this system is added by the [`crate::WindowPlugin`].
 /// To disable this behaviour, set `close_when_requested` (on the [`crate::WindowPlugin`]) to `false`

crates/bevy_window/src/window.rs

@@ -572,6 +572,17 @@ impl Window {
         });
     }
 
+    /// Close the operating system window corresponding to this [`Window`].  
+    /// This will also lead to this [`Window`] being removed from the
+    /// [`Windows`] resource.
+    ///
+    /// If the default [`WindowPlugin`] is used, when no windows are
+    /// open, the [app will exit](bevy_app::AppExit).  
+    /// To disable this behaviour, set `exit_on_all_closed` on the [`WindowPlugin`]
+    /// to `false`
+    ///
+    /// [`Windows`]: crate::Windows
+    /// [`WindowPlugin`]: crate::WindowPlugin
     pub fn close(&mut self) {
         self.command_queue.push(WindowCommand::Close);
     }