Add documentation comments to bevy_winit (#8115)

# 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]>

Author: beeryt

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

crates/bevy_winit/src/lib.rs

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

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

crates/bevy_winit/src/winit_windows.rs

@@ -1,3 +1,4 @@
+#![warn(missing_docs)]
 use std::sync::atomic::Ordering;
 
 use accesskit_winit::Adapter;
@@ -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<()>,
@@ -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::<Vec<_>>();
     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(