Skip to content

Commit

Permalink
Add documentation comments to bevy_winit (#8115)
Browse files Browse the repository at this point in the history
# Objective

- [x] Add documentation comments to `bevy_winit`
- [x] Add `#![warn(missing_docs)]` to `bevy_winit`.

Relates to #3492

---------

Co-authored-by: François <[email protected]>
  • Loading branch information
beeryt and mockersf authored Mar 21, 2023
1 parent 2d5ef75 commit 353f2e0
Show file tree
Hide file tree
Showing 4 changed files with 29 additions and 1 deletion.
2 changes: 2 additions & 0 deletions crates/bevy_winit/src/accessibility.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! Helpers for mapping window entities to accessibility types

use std::{
collections::VecDeque,
sync::{atomic::Ordering, Arc, Mutex},
Expand Down
12 changes: 12 additions & 0 deletions crates/bevy_winit/src/lib.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,11 @@
#![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`](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.

pub mod accessibility;
mod converters;
mod system;
Expand Down Expand Up @@ -49,6 +57,7 @@ use crate::web_resize::{CanvasParentResizeEventChannel, CanvasParentResizePlugin
#[cfg(target_os = "android")]
pub static ANDROID_APP: once_cell::sync::OnceCell<AndroidApp> = once_cell::sync::OnceCell::new();

/// A [`Plugin`] that utilizes [`winit`] for window creation and event loop management.
#[derive(Default)]
pub struct WinitPlugin;

Expand Down Expand Up @@ -270,6 +279,9 @@ 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
Expand Down
2 changes: 1 addition & 1 deletion crates/bevy_winit/src/winit_config.rs
Original file line number Diff line number Diff line change
@@ -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
Expand Down
14 changes: 14 additions & 0 deletions crates/bevy_winit/src/winit_windows.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
#![warn(missing_docs)]
use std::sync::atomic::Ordering;

use accesskit_winit::Adapter;
Expand All @@ -20,18 +21,24 @@ use crate::{
converters::convert_window_level,
};

/// A resource which maps window entities to [`winit`] library windows.
#[derive(Debug, Default)]
pub struct WinitWindows {
/// Stores [`winit`] windows by window identifier.
pub windows: HashMap<winit::window::WindowId, winit::window::Window>,
/// Maps entities to `winit` window identifiers.
pub entity_to_winit: HashMap<Entity, winit::window::WindowId>,
/// Maps `winit` window identifiers to entities.
pub winit_to_entity: HashMap<winit::window::WindowId, Entity>,

// 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.
_not_send_sync: core::marker::PhantomData<*const ()>,
}

impl WinitWindows {
/// Creates a `winit` window and associates it with our entity.
pub fn create_window(
&mut self,
event_loop: &winit::event_loop::EventLoopWindowTarget<()>,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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::<Vec<_>>();
modes.sort_by(|a, b| {
Expand Down Expand Up @@ -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(
Expand Down

0 comments on commit 353f2e0

Please sign in to comment.