Docs: App::run() might never return; effect of WinitSettings::return_…

…from_run. (bevyengine#7228)

# Objective

See:

- bevyengine#7067 (comment)
  - (This does not fully close that issue in my opinion.)
- https://discord.com/channels/691052431525675048/1063454009769340989

## Solution

This merge request adds documentation:

1. Alert users to the fact that `App::run()` might never return and code placed after it might never be executed.
2. Makes `winit::WinitSettings::return_from_run` discoverable.
3. Better explains why `winit::WinitSettings::return_from_run` is discouraged and better links to up-stream docs. on that topic.
4. Adds notes to the `app/return_after_run.rs` example which otherwise promotes a feature that carries caveats.

Furthermore, w.r.t `winit::WinitSettings::return_from_run`:

- Broken links to `winit` docs are fixed.
- Links now point to BOTH `EventLoop::run()` and `EventLoopExtRunReturn::run_return()` which are the salient up-stream pages and make more sense, taken together.
- Collateral damage: "Supported platforms" heading; disambiguation of "run" → `App::run()`; links.
   
## Future Work

I deliberately structured the "`run()` might not return" section under `App::run()` to allow for alternative patterns (e.g. `AppExit` event, `WindowClosed` event) to be listed or mentioned, beneath it, in the future.

crates/bevy_app/src/app.rs

@@ -178,6 +178,24 @@ impl App {
     /// Finalizes the [`App`] configuration. For general usage, see the example on the item
     /// level documentation.
     ///
+    /// # `run()` might not return
+    ///
+    /// Calls to [`App::run()`] might never return.
+    ///
+    /// In simple and *headless* applications, one can expect that execution will
+    /// proceed, normally, after calling [`run()`](App::run()) but this is not the case for
+    /// windowed applications.
+    ///
+    /// Windowed apps are typically driven by an *event loop* or *message loop* and
+    /// some window-manager APIs expect programs to terminate when their primary
+    /// window is closed and that event loop terminates – behaviour of processes that
+    /// do not is often platform dependent or undocumented.
+    ///
+    /// By default, *Bevy* uses the `winit` crate for window creation. See
+    /// [`WinitSettings::return_from_run`](https://docs.rs/bevy/latest/bevy/winit/struct.WinitSettings.html#structfield.return_from_run)
+    /// for further discussion of this topic and for a mechanism to require that [`App::run()`]
+    /// *does* return – albeit one that carries its own caveats and disclaimers.
+    ///
     /// # Panics
     ///
     /// Panics if called from `Plugin::build()`, because it would prevent other plugins to properly build.

crates/bevy_winit/src/winit_config.rs

@@ -4,15 +4,28 @@ use bevy_utils::Duration;
 /// A resource for configuring usage of the `rust_winit` library.
 #[derive(Debug, Resource)]
 pub struct WinitSettings {
-    /// Configures the winit library to return control to the main thread after the
-    /// [run](bevy_app::App::run) loop is exited. Winit strongly recommends avoiding this when
-    /// possible. Before using this please read and understand the
-    /// [caveats](winit::platform::run_return::EventLoopExtRunReturn::run_return) in the winit
-    /// documentation.
+    /// Configures `winit` to return control to the caller after exiting the
+    /// event loop, enabling [`App::run()`](bevy_app::App::run()) to return.
     ///
-    /// This feature is only available on desktop `target_os` configurations. Namely `windows`,
-    /// `macos`, `linux`, `dragonfly`, `freebsd`, `netbsd`, and `openbsd`. If set to true on an
-    /// unsupported platform [run](bevy_app::App::run) will panic.
+    /// By default, [`return_from_run`](Self::return_from_run) is `false` and *Bevy*
+    /// will use `winit`'s
+    /// [`EventLoop::run()`](https://docs.rs/winit/latest/winit/event_loop/struct.EventLoop.html#method.run)
+    /// to initiate the event loop.
+    /// [`EventLoop::run()`](https://docs.rs/winit/latest/winit/event_loop/struct.EventLoop.html#method.run)
+    /// will never return but will terminate the process after the event loop exits.
+    ///
+    /// Setting [`return_from_run`](Self::return_from_run) to `true` will cause *Bevy*
+    /// to use `winit`'s
+    /// [`EventLoopExtRunReturn::run_return()`](https://docs.rs/winit/latest/winit/platform/run_return/trait.EventLoopExtRunReturn.html#tymethod.run_return)
+    /// instead which is strongly discouraged by the `winit` authors.
+    ///
+    /// # Supported platforms
+    ///
+    /// This feature is only available on the following desktop `target_os` configurations:
+    /// `windows`, `macos`, `linux`, `dragonfly`, `freebsd`, `netbsd`, and `openbsd`.
+    ///
+    /// Setting [`return_from_run`](Self::return_from_run) to `true` on
+    /// unsupported platforms will cause [`App::run()`](bevy_app::App::run()) to panic!
     pub return_from_run: bool,
     /// Configures how the winit event loop updates while the window is focused.
     pub focused_mode: UpdateMode,

examples/app/return_after_run.rs

@@ -1,4 +1,15 @@
 //! Shows how to return to the calling function after a windowed Bevy app has exited.
+//!
+//! In windowed *Bevy* applications, executing code below a call to `App::run()` is
+//! not recommended because `App::run()` might never return.
+//!
+//! This example demonstrates the use of `WinitSettings::return_from_run` to
+//! require that `App::run()` *does* return but this is not recommended. Be sure
+//! to read the documentation on both `App::run()` and `WinitSettings::return_from_run`
+//! for caveats and further details:
+//!
+//! - <https://docs.rs/bevy/latest/bevy/app/struct.App.html#method.run>
+//! - <https://docs.rs/bevy/latest/bevy/winit/struct.WinitSettings.html#structfield.return_from_run>
 
 use bevy::{prelude::*, winit::WinitSettings};