[Merged by Bors] - Docs: App::run() might never return; effect of WinitSettings::return_from_run.

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};