From 92b5809470a5b25edbf952e49949743ea83141a3 Mon Sep 17 00:00:00 2001 From: "Carl B. Smiley" Date: Thu, 16 Mar 2023 21:36:11 -0700 Subject: [PATCH 1/8] add documentation comments to `bevy_winit` --- crates/bevy_winit/src/lib.rs | 2 ++ crates/bevy_winit/src/winit_config.rs | 2 +- crates/bevy_winit/src/winit_windows.rs | 14 ++++++++++++++ 3 files changed, 17 insertions(+), 1 deletion(-) diff --git a/crates/bevy_winit/src/lib.rs b/crates/bevy_winit/src/lib.rs index caf74d3eeb0d8..278a9c7e34e45 100644 --- a/crates/bevy_winit/src/lib.rs +++ b/crates/bevy_winit/src/lib.rs @@ -49,6 +49,7 @@ use crate::web_resize::{CanvasParentResizeEventChannel, CanvasParentResizePlugin #[cfg(target_os = "android")] pub static ANDROID_APP: once_cell::sync::OnceCell = once_cell::sync::OnceCell::new(); +/// A [`Plugin`] that utilizes [`winit`] for window creation and event loop management. #[derive(Default)] pub struct WinitPlugin; @@ -270,6 +271,7 @@ impl Default for WinitPersistentState { } } +/// The default [`App::runner`] for the [`WinitPlugin`] plugin. pub fn winit_runner(mut app: App) { // We remove this so that we have ownership over it. let mut event_loop = app diff --git a/crates/bevy_winit/src/winit_config.rs b/crates/bevy_winit/src/winit_config.rs index 40bfd1f87323b..d5627c4b2225b 100644 --- a/crates/bevy_winit/src/winit_config.rs +++ b/crates/bevy_winit/src/winit_config.rs @@ -1,7 +1,7 @@ use bevy_ecs::system::Resource; use bevy_utils::Duration; -/// A resource for configuring usage of the `rust_winit` library. +/// A resource for configuring usage of the [`winit`] library. #[derive(Debug, Resource)] pub struct WinitSettings { /// Configures `winit` to return control to the caller after exiting the diff --git a/crates/bevy_winit/src/winit_windows.rs b/crates/bevy_winit/src/winit_windows.rs index b87678acd3d8d..b7b3080b2e7bf 100644 --- a/crates/bevy_winit/src/winit_windows.rs +++ b/crates/bevy_winit/src/winit_windows.rs @@ -1,3 +1,4 @@ +#![warn(missing_docs)] use std::sync::atomic::Ordering; use accesskit_winit::Adapter; @@ -20,11 +21,16 @@ use crate::{ converters::convert_window_level, }; +/// A reource which maps window entities to [`winit`] library windows. #[derive(Debug, Default)] pub struct WinitWindows { + /// Stores [`winit`] windows by window identifier. pub windows: HashMap, + /// Maps entities to `winit` window identifiers. pub entity_to_winit: HashMap, + /// Maps `winit` window identifiers to entities. pub winit_to_entity: HashMap, + // Some winit functions, such as `set_window_icon` can only be used from the main thread. If // they are used in another thread, the app will hang. This marker ensures `WinitWindows` is // only ever accessed with bevy's non-send functions and in NonSend systems. @@ -32,6 +38,7 @@ pub struct WinitWindows { } impl WinitWindows { + /// Creates a `winit` window and associates it with our entity. pub fn create_window( &mut self, event_loop: &winit::event_loop::EventLoopWindowTarget<()>, @@ -227,6 +234,9 @@ impl WinitWindows { } } +/// Gets the "best" video mode which fits the given dimensions. +/// +/// The heuristic for "best" prioritizes width, height, and refresh rate in that order. pub fn get_fitting_videomode( monitor: &winit::monitor::MonitorHandle, width: u32, @@ -259,6 +269,9 @@ pub fn get_fitting_videomode( modes.first().unwrap().clone() } +/// Gets the "best" videomode from a monitor. +/// +/// The heuristic for "best" prioritizes width, height, and refresh rate in that order. pub fn get_best_videomode(monitor: &winit::monitor::MonitorHandle) -> winit::monitor::VideoMode { let mut modes = monitor.video_modes().collect::>(); modes.sort_by(|a, b| { @@ -300,6 +313,7 @@ pub(crate) fn attempt_grab(winit_window: &winit::window::Window, grab_mode: Curs } } +/// Compute the physical window position for a given [`WindowPosition`]. // Ideally we could generify this across window backends, but we only really have winit atm // so whatever. pub fn winit_window_position( From f058d8a9b02204bcd31ecb38293b903f46f69b47 Mon Sep 17 00:00:00 2001 From: "Carl B. Smiley" Date: Fri, 17 Mar 2023 09:05:12 -0700 Subject: [PATCH 2/8] fix typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: François --- crates/bevy_winit/src/winit_windows.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_winit/src/winit_windows.rs b/crates/bevy_winit/src/winit_windows.rs index b7b3080b2e7bf..6bc5995490714 100644 --- a/crates/bevy_winit/src/winit_windows.rs +++ b/crates/bevy_winit/src/winit_windows.rs @@ -21,7 +21,7 @@ use crate::{ converters::convert_window_level, }; -/// A reource which maps window entities to [`winit`] library windows. +/// A resource which maps window entities to [`winit`] library windows. #[derive(Debug, Default)] pub struct WinitWindows { /// Stores [`winit`] windows by window identifier. From 3bf776f2554473374ce05962e50394c0d18ff8ee Mon Sep 17 00:00:00 2001 From: "Carl B. Smiley" Date: Fri, 17 Mar 2023 09:06:17 -0700 Subject: [PATCH 3/8] add warning for missing docs --- crates/bevy_winit/src/lib.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/crates/bevy_winit/src/lib.rs b/crates/bevy_winit/src/lib.rs index 278a9c7e34e45..ac93440508afc 100644 --- a/crates/bevy_winit/src/lib.rs +++ b/crates/bevy_winit/src/lib.rs @@ -1,3 +1,4 @@ +#![warn(missing_docs)] pub mod accessibility; mod converters; mod system; From 2bb9ac6d410c5bca0a9af461dafde09f3192f5ed Mon Sep 17 00:00:00 2001 From: "Carl B. Smiley" Date: Fri, 17 Mar 2023 09:15:09 -0700 Subject: [PATCH 4/8] add basic description for `bevy_winit::accessibility` --- crates/bevy_winit/src/accessibility.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/crates/bevy_winit/src/accessibility.rs b/crates/bevy_winit/src/accessibility.rs index 68eff9b21462e..4bda4319a5784 100644 --- a/crates/bevy_winit/src/accessibility.rs +++ b/crates/bevy_winit/src/accessibility.rs @@ -1,3 +1,5 @@ +//! Helpers for mapping window entities to accessibility types + use std::{ collections::VecDeque, sync::{atomic::Ordering, Arc, Mutex}, From 2bf7bd56554c4d4baaad1bf142486beaee1f7f92 Mon Sep 17 00:00:00 2001 From: "Carl B. Smiley" Date: Fri, 17 Mar 2023 10:07:13 -0700 Subject: [PATCH 5/8] add crate-level description --- crates/bevy_winit/src/lib.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/crates/bevy_winit/src/lib.rs b/crates/bevy_winit/src/lib.rs index ac93440508afc..d5efc9ebc4cd0 100644 --- a/crates/bevy_winit/src/lib.rs +++ b/crates/bevy_winit/src/lib.rs @@ -1,4 +1,10 @@ #![warn(missing_docs)] +//! `bevy_winit` provides utilities to handle window creation and the eventloop through [`winit`] +//! +//! Most commonly, the [`WinitPlugin`] is used as part of [`DefaultPlugins`](bevy::DefaultPlugins). +//! The app's [runner](bevy_app::App::runner) is set by `WinitPlugin` and handles the [`winit::EventLoop`]. +//! See `winit_runner` for details. + pub mod accessibility; mod converters; mod system; @@ -273,6 +279,8 @@ impl Default for WinitPersistentState { } /// The default [`App::runner`] for the [`WinitPlugin`] plugin. +/// +/// Overriding the app's [runner](bevy_app::App::runner) while using `WinitPlugin` will bypass the `EventLoop`. pub fn winit_runner(mut app: App) { // We remove this so that we have ownership over it. let mut event_loop = app From aecb69c84e065beb72a64bb4ac6e6bd01101ba31 Mon Sep 17 00:00:00 2001 From: "Carl B. Smiley" Date: Fri, 17 Mar 2023 10:34:31 -0700 Subject: [PATCH 6/8] fix crate scoping in doc comments --- crates/bevy_winit/src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/bevy_winit/src/lib.rs b/crates/bevy_winit/src/lib.rs index d5efc9ebc4cd0..808caf79a0e84 100644 --- a/crates/bevy_winit/src/lib.rs +++ b/crates/bevy_winit/src/lib.rs @@ -1,8 +1,8 @@ #![warn(missing_docs)] //! `bevy_winit` provides utilities to handle window creation and the eventloop through [`winit`] //! -//! Most commonly, the [`WinitPlugin`] is used as part of [`DefaultPlugins`](bevy::DefaultPlugins). -//! The app's [runner](bevy_app::App::runner) is set by `WinitPlugin` and handles the [`winit::EventLoop`]. +//! Most commonly, the [`WinitPlugin`] is used as part of [`DefaultPlugins`](crate::bevy::DefaultPlugins). +//! The app's [runner](bevy_app::App::runner) is set by `WinitPlugin` and handles the `winit` [`EventLoop`](winit::event_loop::EventLoop). //! See `winit_runner` for details. pub mod accessibility; From b2a04ada2355227d7c72cb1a30d887789cc64d56 Mon Sep 17 00:00:00 2001 From: "Carl B. Smiley" Date: Fri, 17 Mar 2023 10:48:35 -0700 Subject: [PATCH 7/8] fix scoping in doc comments --- crates/bevy_winit/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_winit/src/lib.rs b/crates/bevy_winit/src/lib.rs index 808caf79a0e84..2b83e750e4dbe 100644 --- a/crates/bevy_winit/src/lib.rs +++ b/crates/bevy_winit/src/lib.rs @@ -1,7 +1,7 @@ #![warn(missing_docs)] //! `bevy_winit` provides utilities to handle window creation and the eventloop through [`winit`] //! -//! Most commonly, the [`WinitPlugin`] is used as part of [`DefaultPlugins`](crate::bevy::DefaultPlugins). +//! Most commonly, the [`WinitPlugin`] is used as part of [`DefaultPlugins`](bevy_internal::DefaultPlugins). //! The app's [runner](bevy_app::App::runner) is set by `WinitPlugin` and handles the `winit` [`EventLoop`](winit::event_loop::EventLoop). //! See `winit_runner` for details. From 4340fe65566bda21c8e361dc02f5af091f409a72 Mon Sep 17 00:00:00 2001 From: "Carl B. Smiley" Date: Fri, 17 Mar 2023 12:14:02 -0700 Subject: [PATCH 8/8] use hardcoded link since bevy_internal is not a dep --- crates/bevy_winit/src/lib.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/crates/bevy_winit/src/lib.rs b/crates/bevy_winit/src/lib.rs index 2b83e750e4dbe..dec1a9076be24 100644 --- a/crates/bevy_winit/src/lib.rs +++ b/crates/bevy_winit/src/lib.rs @@ -1,7 +1,8 @@ #![warn(missing_docs)] //! `bevy_winit` provides utilities to handle window creation and the eventloop through [`winit`] //! -//! Most commonly, the [`WinitPlugin`] is used as part of [`DefaultPlugins`](bevy_internal::DefaultPlugins). +//! Most commonly, the [`WinitPlugin`] is used as part of +//! [`DefaultPlugins`](https://docs.rs/bevy/latest/bevy/struct.DefaultPlugins.html). //! The app's [runner](bevy_app::App::runner) is set by `WinitPlugin` and handles the `winit` [`EventLoop`](winit::event_loop::EventLoop). //! See `winit_runner` for details.