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

…from_run. (#7228)

# Objective

See:

- bevyengine/bevy#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.

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,