Documentation cleanup (#2328)

* Remove redundant documentation links

* Add note to README about windows not showing up on Wayland

* Fix documentation links

* Small documentation fixes

* Add note about doing stuff after StartCause::Init on macOS

README.md

@@ -69,6 +69,14 @@ Winit provides the following features, which can be enabled in your `Cargo.toml`
 
 ### Platform-specific usage
 
+#### Wayland
+
+Note that windows don't appear on Wayland until you draw/present to them.
+
+`winit` doesn't do drawing, try the examples in [`glutin`] instead.
+
+[`glutin`]: https://github.com/rust-windowing/glutin
+
 #### WebAssembly
 
 To run the web example: `cargo run-wasm --example web`
@@ -121,3 +129,16 @@ fn main() {
 ```
 
 And run the application with `cargo apk run --example request_redraw_threaded`
+
+#### MacOS
+
+A lot of functionality expects the application to be ready before you start
+doing anything; this includes creating windows, fetching monitors, drawing,
+and so on, see issues [#2238], [#2051] and [#2087].
+
+If you encounter problems, you should try doing your initialization inside
+`Event::NewEvents(StartCause::Init)`.
+
+[#2238]: https://github.com/rust-windowing/winit/issues/2238
+[#2051]: https://github.com/rust-windowing/winit/issues/2051
+[#2087]: https://github.com/rust-windowing/winit/issues/2087

src/dpi.rs

@@ -35,8 +35,9 @@
 //!
 //! ### Position and Size types
 //!
-//! Winit's `Physical(Position|Size)` types correspond with the actual pixels on the device, and the
+//! Winit's [`PhysicalPosition`] / [`PhysicalSize`] types correspond with the actual pixels on the
-//! `Logical(Position|Size)` types correspond to the physical pixels divided by the scale factor.
+//! device, and the [`LogicalPosition`] / [`LogicalSize`] types correspond to the physical pixels
+//! divided by the scale factor.
 //! All of Winit's functions return physical types, but can take either logical or physical
 //! coordinates as input, allowing you to use the most convenient coordinate system for your
 //! particular application.
@@ -46,19 +47,18 @@
 //! floating precision when necessary (e.g. logical sizes for fractional scale factors and touch
 //! input). If `P` is a floating-point type, please do not cast the values with `as {int}`. Doing so
 //! will truncate the fractional part of the float, rather than properly round to the nearest
-//! integer. Use the provided `cast` function or `From`/`Into` conversions, which handle the
+//! integer. Use the provided `cast` function or [`From`]/[`Into`] conversions, which handle the
 //! rounding properly. Note that precision loss will still occur when rounding from a float to an
 //! int, although rounding lessens the problem.
 //!
 //! ### Events
 //!
-//! Winit will dispatch a [`ScaleFactorChanged`](crate::event::WindowEvent::ScaleFactorChanged)
+//! Winit will dispatch a [`ScaleFactorChanged`] event whenever a window's scale factor has changed.
-//! event whenever a window's scale factor has changed. This can happen if the user drags their
+//! This can happen if the user drags their window from a standard-resolution monitor to a high-DPI
-//! window from a standard-resolution monitor to a high-DPI monitor, or if the user changes their
+//! monitor, or if the user changes their DPI settings. This gives you a chance to rescale your
-//! DPI settings. This gives you a chance to rescale your application's UI elements and adjust how
+//! application's UI elements and adjust how the platform changes the window's size to reflect the new
-//! the platform changes the window's size to reflect the new scale factor. If a window hasn't
+//! scale factor. If a window hasn't received a [`ScaleFactorChanged`] event,  then its scale factor
-//! received a [`ScaleFactorChanged`](crate::event::WindowEvent::ScaleFactorChanged) event,
+//! can be found by calling [`window.scale_factor()`].
-//! then its scale factor can be found by calling [window.scale_factor()].
 //!
 //! ## How is the scale factor calculated?
 //!
@@ -93,9 +93,11 @@
 //!   In other words, it is the value of [`window.devicePixelRatio`][web_1]. It is affected by
 //!   both the screen scaling and the browser zoom level and can go below `1.0`.
 //!
+//!
 //! [points]: https://en.wikipedia.org/wiki/Point_(typography)
 //! [picas]: https://en.wikipedia.org/wiki/Pica_(typography)
-//! [window.scale_factor()]: crate::window::Window::scale_factor
+//! [`ScaleFactorChanged`]: crate::event::WindowEvent::ScaleFactorChanged
+//! [`window.scale_factor()`]: crate::window::Window::scale_factor
 //! [windows_1]: https://docs.microsoft.com/en-us/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows
 //! [apple_1]: https://developer.apple.com/library/archive/documentation/DeviceInformation/Reference/iOSDeviceCompatibility/Displays/Displays.html
 //! [apple_2]: https://developer.apple.com/design/human-interface-guidelines/macos/icons-and-images/image-size-and-resolution/

src/event.rs

@@ -1,10 +1,10 @@
-//! The `Event` enum and assorted supporting types.
+//! The [`Event`] enum and assorted supporting types.
 //!
-//! These are sent to the closure given to [`EventLoop::run(...)`][event_loop_run], where they get
+//! These are sent to the closure given to [`EventLoop::run(...)`], where they get
 //! processed and used to modify the program state. For more details, see the root-level documentation.
 //!
 //! Some of these events represent different "parts" of a traditional event-handling loop. You could
-//! approximate the basic ordering loop of [`EventLoop::run(...)`][event_loop_run] like this:
+//! approximate the basic ordering loop of [`EventLoop::run(...)`] like this:
 //!
 //! ```rust,ignore
 //! let mut control_flow = ControlFlow::Poll;
@@ -29,10 +29,11 @@
 //! event_handler(LoopDestroyed, ..., &mut control_flow);
 //! ```
 //!
-//! This leaves out timing details like `ControlFlow::WaitUntil` but hopefully
+//! This leaves out timing details like [`ControlFlow::WaitUntil`] but hopefully
 //! describes what happens in what order.
 //!
-//! [event_loop_run]: crate::event_loop::EventLoop::run
+//! [`EventLoop::run(...)`]: crate::event_loop::EventLoop::run
+//! [`ControlFlow::WaitUntil`]: crate::event_loop::ControlFlow::WaitUntil
 use instant::Instant;
 use std::path::PathBuf;
 
@@ -90,7 +91,7 @@ pub enum Event<'a, T: 'static> {
     /// can render here unconditionally for simplicity.
     MainEventsCleared,
 
-    /// Emitted after `MainEventsCleared` when a window should be redrawn.
+    /// Emitted after [`MainEventsCleared`] when a window should be redrawn.
     ///
     /// This gets triggered in two scenarios:
     /// - The OS has performed an operation that's invalidated the window's contents (such as
@@ -102,14 +103,18 @@ pub enum Event<'a, T: 'static> {
     ///
     /// Mainly of interest to applications with mostly-static graphics that avoid redrawing unless
     /// something changes, like most non-game GUIs.
+    ///
+    /// [`MainEventsCleared`]: Self::MainEventsCleared
     RedrawRequested(WindowId),
 
-    /// Emitted after all `RedrawRequested` events have been processed and control flow is about to
+    /// Emitted after all [`RedrawRequested`] events have been processed and control flow is about to
     /// be taken away from the program. If there are no `RedrawRequested` events, it is emitted
     /// immediately after `MainEventsCleared`.
     ///
     /// This event is useful for doing any cleanup or bookkeeping work after all the rendering
     /// tasks have been completed.
+    ///
+    /// [`RedrawRequested`]: Self::RedrawRequested
     RedrawEventsCleared,
 
     /// Emitted when the event loop is being shut down.
@@ -184,9 +189,11 @@ impl<'a, T> Event<'a, T> {
 /// Describes the reason the event loop is resuming.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum StartCause {
-    /// Sent if the time specified by `ControlFlow::WaitUntil` has been reached. Contains the
+    /// Sent if the time specified by [`ControlFlow::WaitUntil`] has been reached. Contains the
     /// moment the timeout was requested and the requested resume time. The actual resume time is
     /// guaranteed to be equal to or after the requested resume time.
+    ///
+    /// [`ControlFlow::WaitUntil`]: crate::event_loop::ControlFlow::WaitUntil
     ResumeTimeReached {
         start: Instant,
         requested_resume: Instant,
@@ -200,7 +207,9 @@ pub enum StartCause {
     },
 
     /// Sent if the event loop is being resumed after the loop's control flow was set to
-    /// `ControlFlow::Poll`.
+    /// [`ControlFlow::Poll`].
+    ///
+    /// [`ControlFlow::Poll`]: crate::event_loop::ControlFlow::Poll
     Poll,
 
     /// Sent once, immediately after `run` is called. Indicates that the loop was just initialized.
@@ -550,7 +559,7 @@ impl<'a> WindowEvent<'a> {
 pub struct DeviceId(pub(crate) platform_impl::DeviceId);
 
 impl DeviceId {
-    /// Returns a dummy `DeviceId`, useful for unit testing.
+    /// Returns a dummy id, useful for unit testing.
     ///
     /// # Safety
     ///
@@ -579,7 +588,7 @@ pub enum DeviceEvent {
 
     /// Change in physical position of a pointing device.
     ///
-    /// This represents raw, unfiltered physical motion. Not to be confused with `WindowEvent::CursorMoved`.
+    /// This represents raw, unfiltered physical motion. Not to be confused with [`WindowEvent::CursorMoved`].
     MouseMotion {
         /// (x, y) change in position in unspecified units.
         ///
@@ -673,7 +682,6 @@ pub struct KeyboardInput {
 /// // Press space key
 /// Ime::Commit("啊不")
 /// ```
-///
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub enum Ime {
@@ -718,18 +726,18 @@ pub enum TouchPhase {
 
 /// Represents a touch event
 ///
-/// Every time the user touches the screen, a new `Start` event with an unique
+/// Every time the user touches the screen, a new [`TouchPhase::Started`] event with an unique
-/// identifier for the finger is generated. When the finger is lifted, an `End`
+/// identifier for the finger is generated. When the finger is lifted, an [`TouchPhase::Ended`]
 /// event is generated with the same finger id.
 ///
-/// After a `Start` event has been emitted, there may be zero or more `Move`
+/// After a `Started` event has been emitted, there may be zero or more `Move`
 /// events when the finger is moved or the touch pressure changes.
 ///
-/// The finger id may be reused by the system after an `End` event. The user
+/// The finger id may be reused by the system after an `Ended` event. The user
-/// should assume that a new `Start` event received with the same id has nothing
+/// should assume that a new `Started` event received with the same id has nothing
 /// to do with the old finger and is a new finger.
 ///
-/// A `Cancelled` event is emitted when the system has canceled tracking this
+/// A [`TouchPhase::Cancelled`] event is emitted when the system has canceled tracking this
 /// touch, such as when the window loses focus, or on iOS if the user moves the
 /// device against their face.
 #[derive(Debug, Clone, Copy, PartialEq)]
@@ -783,8 +791,9 @@ pub enum Force {
 
 impl Force {
     /// Returns the force normalized to the range between 0.0 and 1.0 inclusive.
+    ///
     /// Instead of normalizing the force, you should prefer to handle
-    /// `Force::Calibrated` so that the amount of force the user has to apply is
+    /// [`Force::Calibrated`] so that the amount of force the user has to apply is
     /// consistent across devices.
     pub fn normalized(&self) -> f64 {
         match self {
@@ -845,7 +854,7 @@ pub enum MouseScrollDelta {
     /// Amount in pixels to scroll in the horizontal and
     /// vertical direction.
     ///
-    /// Scroll events are expressed as a PixelDelta if
+    /// Scroll events are expressed as a `PixelDelta` if
     /// supported by the device (eg. a touchpad) and
     /// platform.
     ///

src/event_loop.rs

@@ -1,14 +1,12 @@
-//! The `EventLoop` struct and assorted supporting types, including `ControlFlow`.
+//! The [`EventLoop`] struct and assorted supporting types, including
+//! [`ControlFlow`].
 //!
-//! If you want to send custom events to the event loop, use [`EventLoop::create_proxy()`][create_proxy]
+//! If you want to send custom events to the event loop, use
-//! to acquire an [`EventLoopProxy`][event_loop_proxy] and call its [`send_event`][send_event] method.
+//! [`EventLoop::create_proxy`] to acquire an [`EventLoopProxy`] and call its
+//! [`send_event`](`EventLoopProxy::send_event`) method.
 //!
 //! See the root-level documentation for information on how to create and use an event loop to
 //! handle events.
-//!
-//! [create_proxy]: crate::event_loop::EventLoop::create_proxy
-//! [event_loop_proxy]: crate::event_loop::EventLoopProxy
-//! [send_event]: crate::event_loop::EventLoopProxy::send_event
 use instant::Instant;
 use std::marker::PhantomData;
 use std::ops::Deref;
@@ -19,26 +17,27 @@ use crate::{event::Event, monitor::MonitorHandle, platform_impl};
 /// Provides a way to retrieve events from the system and from the windows that were registered to
 /// the events loop.
 ///
-/// An `EventLoop` can be seen more or less as a "context". Calling `EventLoop::new()`
+/// An `EventLoop` can be seen more or less as a "context". Calling [`EventLoop::new`]
 /// initializes everything that will be required to create windows. For example on Linux creating
 /// an event loop opens a connection to the X or Wayland server.
 ///
-/// To wake up an `EventLoop` from a another thread, see the `EventLoopProxy` docs.
+/// To wake up an `EventLoop` from a another thread, see the [`EventLoopProxy`] docs.
 ///
-/// Note that the `EventLoop` cannot be shared across threads (due to platform-dependant logic
+/// Note that this cannot be shared across threads (due to platform-dependant logic
-/// forbidding it), as such it is neither `Send` nor `Sync`. If you need cross-thread access, the
+/// forbidding it), as such it is neither [`Send`] nor [`Sync`]. If you need cross-thread access, the
-/// `Window` created from this `EventLoop` _can_ be sent to an other thread, and the
+/// [`Window`] created from this _can_ be sent to an other thread, and the
-/// `EventLoopProxy` allows you to wake up an `EventLoop` from another thread.
+/// [`EventLoopProxy`] allows you to wake up an `EventLoop` from another thread.
 ///
+/// [`Window`]: crate::window::Window
 pub struct EventLoop<T: 'static> {
     pub(crate) event_loop: platform_impl::EventLoop<T>,
     pub(crate) _marker: PhantomData<*mut ()>, // Not Send nor Sync
 }
 
-/// Target that associates windows with an `EventLoop`.
+/// Target that associates windows with an [`EventLoop`].
 ///
 /// This type exists to allow you to create new windows while Winit executes
-/// your callback. `EventLoop` will coerce into this type (`impl<T> Deref for
+/// your callback. [`EventLoop`] will coerce into this type (`impl<T> Deref for
 /// EventLoop<T>`), so functions that take this as a parameter can also take
 /// `&EventLoop`.
 pub struct EventLoopWindowTarget<T: 'static> {
@@ -77,11 +76,11 @@ impl<T> EventLoopBuilder<T> {
 
     /// Builds a new event loop.
     ///
-    /// ***For cross-platform compatibility, the `EventLoop` must be created on the main thread.***
+    /// ***For cross-platform compatibility, the [`EventLoop`] must be created on the main thread.***
     /// Attempting to create the event loop on a different thread will panic. This restriction isn't
     /// strictly necessary on all platforms, but is imposed to eliminate any nasty surprises when
     /// porting to platforms that require it. `EventLoopBuilderExt::any_thread` functions are exposed
-    /// in the relevant `platform` module if the target platform supports creating an event loop on
+    /// in the relevant [`platform`] module if the target platform supports creating an event loop on
     /// any thread.
     ///
     /// Calling this function will result in display backend initialisation.
@@ -92,6 +91,8 @@ impl<T> EventLoopBuilder<T> {
     ///   `WINIT_UNIX_BACKEND`. Legal values are `x11` and `wayland`.
     ///   If it is not set, winit will try to connect to a Wayland connection, and if that fails,
     ///   will fall back on X11. If this variable is set with any other value, winit will panic.
+    ///
+    /// [`platform`]: crate::platform
     #[inline]
     pub fn build(&mut self) -> EventLoop<T> {
         // Certain platforms accept a mutable reference in their API.
@@ -115,18 +116,21 @@ impl<T> fmt::Debug for EventLoopWindowTarget<T> {
     }
 }
 
-/// Set by the user callback given to the `EventLoop::run` method.
+/// Set by the user callback given to the [`EventLoop::run`] method.
 ///
-/// Indicates the desired behavior of the event loop after [`Event::RedrawEventsCleared`][events_cleared]
+/// Indicates the desired behavior of the event loop after [`Event::RedrawEventsCleared`] is emitted.
-/// is emitted. Defaults to `Poll`.
+///
+/// Defaults to [`Poll`].
 ///
 /// ## Persistency
-/// Almost every change is persistent between multiple calls to the event loop closure within a
-/// given run loop. The only exception to this is `ExitWithCode` which, once set, cannot be unset.
-/// Changes are **not** persistent between multiple calls to `run_return` - issuing a new call will
-/// reset the control flow to `Poll`.
 ///
-/// [events_cleared]: crate::event::Event::RedrawEventsCleared
+/// Almost every change is persistent between multiple calls to the event loop closure within a
+/// given run loop. The only exception to this is [`ExitWithCode`] which, once set, cannot be unset.
+/// Changes are **not** persistent between multiple calls to `run_return` - issuing a new call will
+/// reset the control flow to [`Poll`].
+///
+/// [`ExitWithCode`]: Self::ExitWithCode
+/// [`Poll`]: Self::Poll
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub enum ControlFlow {
     /// When the current loop iteration finishes, immediately begin a new iteration regardless of
@@ -144,10 +148,12 @@ pub enum ControlFlow {
     /// arrives or the given time is reached.
     ///
     /// Useful for implementing efficient timers. Applications which want to render at the display's
-    /// native refresh rate should instead use `Poll` and the VSync functionality of a graphics API
+    /// native refresh rate should instead use [`Poll`] and the VSync functionality of a graphics API
     /// to reduce odds of missed frames.
+    ///
+    /// [`Poll`]: Self::Poll
     WaitUntil(Instant),
-    /// Send a `LoopDestroyed` event and stop the event loop. This variant is *sticky* - once set,
+    /// Send a [`LoopDestroyed`] event and stop the event loop. This variant is *sticky* - once set,
     /// `control_flow` cannot be changed from `ExitWithCode`, and any future attempts to do so will
     /// result in the `control_flow` parameter being reset to `ExitWithCode`.
     ///
@@ -161,6 +167,7 @@ pub enum ControlFlow {
     ///   which can cause surprises with negative exit values (`-42` would end up as `214`). See
     ///   [`std::process::exit`].
     ///
+    /// [`LoopDestroyed`]: Event::LoopDestroyed
     /// [`Exit`]: ControlFlow::Exit
     ExitWithCode(i32),
 }
@@ -168,41 +175,41 @@ pub enum ControlFlow {
 impl ControlFlow {
     /// Alias for [`ExitWithCode`]`(0)`.
     ///
-    /// [`ExitWithCode`]: ControlFlow::ExitWithCode
+    /// [`ExitWithCode`]: Self::ExitWithCode
     #[allow(non_upper_case_globals)]
     pub const Exit: Self = Self::ExitWithCode(0);
 
     /// Sets this to [`Poll`].
     ///
-    /// [`Poll`]: ControlFlow::Poll
+    /// [`Poll`]: Self::Poll
     pub fn set_poll(&mut self) {
         *self = Self::Poll;
     }
 
     /// Sets this to [`Wait`].
     ///
-    /// [`Wait`]: ControlFlow::Wait
+    /// [`Wait`]: Self::Wait
     pub fn set_wait(&mut self) {
         *self = Self::Wait;
     }
 
     /// Sets this to [`WaitUntil`]`(instant)`.
     ///
-    /// [`WaitUntil`]: ControlFlow::WaitUntil
+    /// [`WaitUntil`]: Self::WaitUntil
     pub fn set_wait_until(&mut self, instant: Instant) {
         *self = Self::WaitUntil(instant);
     }
 
     /// Sets this to [`ExitWithCode`]`(code)`.
     ///
-    /// [`ExitWithCode`]: ControlFlow::ExitWithCode
+    /// [`ExitWithCode`]: Self::ExitWithCode
     pub fn set_exit_with_code(&mut self, code: i32) {
         *self = Self::ExitWithCode(code);
     }
 
     /// Sets this to [`Exit`].
     ///
-    /// [`Exit`]: ControlFlow::Exit
+    /// [`Exit`]: Self::Exit
     pub fn set_exit(&mut self) {
         *self = Self::Exit;
     }
@@ -210,13 +217,15 @@ impl ControlFlow {
 
 impl Default for ControlFlow {
     #[inline(always)]
-    fn default() -> ControlFlow {
+    fn default() -> Self {
-        ControlFlow::Poll
+        Self::Poll
     }
 }
 
 impl EventLoop<()> {
-    /// Alias for `EventLoopBuilder::new().build()`.
+    /// Alias for [`EventLoopBuilder::new().build()`].
+    ///
+    /// [`EventLoopBuilder::new().build()`]: EventLoopBuilder::build
     #[inline]
     pub fn new() -> EventLoop<()> {
         EventLoopBuilder::new().build()
@@ -258,7 +267,7 @@ impl<T> EventLoop<T> {
         self.event_loop.run(event_handler)
     }
 
-    /// Creates an `EventLoopProxy` that can be used to dispatch user events to the main event loop.
+    /// Creates an [`EventLoopProxy`] that can be used to dispatch user events to the main event loop.
     pub fn create_proxy(&self) -> EventLoopProxy<T> {
         EventLoopProxy {
             event_loop_proxy: self.event_loop.create_proxy(),
@@ -318,7 +327,7 @@ impl<T> EventLoopWindowTarget<T> {
     }
 }
 
-/// Used to send custom events to `EventLoop`.
+/// Used to send custom events to [`EventLoop`].
 pub struct EventLoopProxy<T: 'static> {
     event_loop_proxy: platform_impl::EventLoopProxy<T>,
 }
@@ -332,11 +341,13 @@ impl<T: 'static> Clone for EventLoopProxy<T> {
 }
 
 impl<T: 'static> EventLoopProxy<T> {
-    /// Send an event to the `EventLoop` from which this proxy was created. This emits a
+    /// Send an event to the [`EventLoop`] from which this proxy was created. This emits a
     /// `UserEvent(event)` event in the event loop, where `event` is the value passed to this
     /// function.
     ///
-    /// Returns an `Err` if the associated `EventLoop` no longer exists.
+    /// Returns an `Err` if the associated [`EventLoop`] no longer exists.
+    ///
+    /// [`UserEvent(event)`]: Event::UserEvent
     pub fn send_event(&self, event: T) -> Result<(), EventLoopClosed<T>> {
         self.event_loop_proxy.send_event(event)
     }
@@ -348,8 +359,10 @@ impl<T: 'static> fmt::Debug for EventLoopProxy<T> {
     }
 }
 
-/// The error that is returned when an `EventLoopProxy` attempts to wake up an `EventLoop` that
+/// The error that is returned when an [`EventLoopProxy`] attempts to wake up an [`EventLoop`] that
-/// no longer exists. Contains the original event given to `send_event`.
+/// no longer exists.
+///
+/// Contains the original event given to [`EventLoopProxy::send_event`].
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
 pub struct EventLoopClosed<T>(pub T);
 

src/icon.rs

@@ -13,7 +13,7 @@ pub(crate) struct Pixel {
 pub(crate) const PIXEL_SIZE: usize = mem::size_of::<Pixel>();
 
 #[derive(Debug)]
-/// An error produced when using `Icon::from_rgba` with invalid arguments.
+/// An error produced when using [`Icon::from_rgba`] with invalid arguments.
 pub enum BadIcon {
     /// Produced when the length of the `rgba` argument isn't divisible by 4, thus `rgba` can't be
     /// safely interpreted as 32bpp RGBA pixels.
@@ -73,10 +73,6 @@ mod constructors {
     use super::*;
 
     impl RgbaIcon {
-        /// Creates an `Icon` from 32bpp RGBA data.
-        ///
-        /// The length of `rgba` must be divisible by 4, and `width * height` must equal
-        /// `rgba.len() / 4`. Otherwise, this will return a `BadIcon` error.
         pub fn from_rgba(rgba: Vec<u8>, width: u32, height: u32) -> Result<Self, BadIcon> {
             if rgba.len() % PIXEL_SIZE != 0 {
                 return Err(BadIcon::ByteCountNotDivisibleBy4 {
@@ -123,7 +119,7 @@ impl fmt::Debug for Icon {
 }
 
 impl Icon {
-    /// Creates an `Icon` from 32bpp RGBA data.
+    /// Creates an icon from 32bpp RGBA data.
     ///
     /// The length of `rgba` must be divisible by 4, and `width * height` must equal
     /// `rgba.len() / 4`. Otherwise, this will return a `BadIcon` error.

src/monitor.rs

@@ -1,14 +1,10 @@
 //! Types useful for interacting with a user's monitors.
 //!
-//! If you want to get basic information about a monitor, you can use the [`MonitorHandle`][monitor_handle]
+//! If you want to get basic information about a monitor, you can use the
-//! type. This is retrieved from one of the following methods, which return an iterator of
+//! [`MonitorHandle`] type. This is retrieved from one of the following
-//! [`MonitorHandle`][monitor_handle]:
+//! methods, which return an iterator of [`MonitorHandle`]:
-//! - [`EventLoopWindowTarget::available_monitors`][loop_get]
+//! - [`EventLoopWindowTarget::available_monitors`](crate::event_loop::EventLoopWindowTarget::available_monitors).
-//! - [`Window::available_monitors`][window_get].
+//! - [`Window::available_monitors`](crate::window::Window::available_monitors).
-//!
-//! [monitor_handle]: crate::monitor::MonitorHandle
-//! [loop_get]: crate::event_loop::EventLoopWindowTarget::available_monitors
-//! [window_get]: crate::window::Window::available_monitors
 use crate::{
     dpi::{PhysicalPosition, PhysicalSize},
     platform_impl,
@@ -16,10 +12,7 @@ use crate::{
 
 /// Describes a fullscreen video mode of a monitor.
 ///
-/// Can be acquired with:
+/// Can be acquired with [`MonitorHandle::video_modes`].
-/// - [`MonitorHandle::video_modes`][monitor_get].
-///
-/// [monitor_get]: crate::monitor::MonitorHandle::video_modes
 #[derive(Clone, PartialEq, Eq, Hash)]
 pub struct VideoMode {
     pub(crate) video_mode: platform_impl::VideoMode,

src/platform/android.rs

@@ -7,15 +7,15 @@ use crate::{
 use ndk::configuration::Configuration;
 use ndk_glue::Rect;
 
-/// Additional methods on `EventLoop` that are specific to Android.
+/// Additional methods on [`EventLoop`] that are specific to Android.
 pub trait EventLoopExtAndroid {}
 
 impl<T> EventLoopExtAndroid for EventLoop<T> {}
 
-/// Additional methods on `EventLoopWindowTarget` that are specific to Android.
+/// Additional methods on [`EventLoopWindowTarget`] that are specific to Android.
 pub trait EventLoopWindowTargetExtAndroid {}
 
-/// Additional methods on `Window` that are specific to Android.
+/// Additional methods on [`Window`] that are specific to Android.
 pub trait WindowExtAndroid {
     fn content_rect(&self) -> Rect;
 
@@ -34,7 +34,7 @@ impl WindowExtAndroid for Window {
 
 impl<T> EventLoopWindowTargetExtAndroid for EventLoopWindowTarget<T> {}
 
-/// Additional methods on `WindowBuilder` that are specific to Android.
+/// Additional methods on [`WindowBuilder`] that are specific to Android.
 pub trait WindowBuilderExtAndroid {}
 
 impl WindowBuilderExtAndroid for WindowBuilder {}

src/platform/macos.rs

@@ -9,16 +9,16 @@ use crate::{
     window::{Window, WindowBuilder},
 };
 
-/// Additional methods on `Window` that are specific to MacOS.
+/// Additional methods on [`Window`] that are specific to MacOS.
 pub trait WindowExtMacOS {
     /// Returns a pointer to the cocoa `NSWindow` that is used by this window.
     ///
-    /// The pointer will become invalid when the `Window` is destroyed.
+    /// The pointer will become invalid when the [`Window`] is destroyed.
     fn ns_window(&self) -> *mut c_void;
 
     /// Returns a pointer to the cocoa `NSView` that is used by this window.
     ///
-    /// The pointer will become invalid when the `Window` is destroyed.
+    /// The pointer will become invalid when the [`Window`] is destroyed.
     fn ns_view(&self) -> *mut c_void;
 
     /// Returns whether or not the window is in simple fullscreen mode.
@@ -89,11 +89,9 @@ impl Default for ActivationPolicy {
     }
 }
 
-/// Additional methods on `WindowBuilder` that are specific to MacOS.
+/// Additional methods on [`WindowBuilder`] that are specific to MacOS.
-///
-/// **Note:** Properties dealing with the titlebar will be overwritten by the `with_decorations` method
-/// on the base `WindowBuilder`:
 ///
+/// **Note:** Properties dealing with the titlebar will be overwritten by the [`WindowBuilder::with_decorations`] method:
 /// - `with_titlebar_transparent`
 /// - `with_title_hidden`
 /// - `with_titlebar_hidden`
@@ -238,7 +236,7 @@ impl<T> EventLoopBuilderExtMacOS for EventLoopBuilder<T> {
     }
 }
 
-/// Additional methods on `MonitorHandle` that are specific to MacOS.
+/// Additional methods on [`MonitorHandle`] that are specific to MacOS.
 pub trait MonitorHandleExtMacOS {
     /// Returns the identifier of the monitor for Cocoa.
     fn native_id(&self) -> u32;
@@ -257,7 +255,7 @@ impl MonitorHandleExtMacOS for MonitorHandle {
     }
 }
 
-/// Additional methods on `EventLoopWindowTarget` that are specific to macOS.
+/// Additional methods on [`EventLoopWindowTarget`] that are specific to macOS.
 pub trait EventLoopWindowTargetExtMacOS {
     /// Hide the entire application. In most applications this is typically triggered with Command-H.
     fn hide_application(&self);

src/platform/mod.rs

@@ -19,7 +19,7 @@ pub mod android;
 pub mod ios;
 pub mod macos;
 pub mod unix;
+pub mod web;
 pub mod windows;
 
 pub mod run_return;
-pub mod web;

src/platform/run_return.rs

@@ -14,17 +14,18 @@ use crate::{
     event_loop::{ControlFlow, EventLoop, EventLoopWindowTarget},
 };
 
-/// Additional methods on `EventLoop` to return control flow to the caller.
+/// Additional methods on [`EventLoop`] to return control flow to the caller.
 pub trait EventLoopExtRunReturn {
-    /// A type provided by the user that can be passed through `Event::UserEvent`.
+    /// A type provided by the user that can be passed through [`Event::UserEvent`].
     type UserEvent;
 
     /// Initializes the `winit` event loop.
     ///
-    /// Unlike `run`, this function accepts non-`'static` (i.e. non-`move`) closures and returns
+    /// Unlike [`EventLoop::run`], this function accepts non-`'static` (i.e. non-`move`) closures
-    /// control flow to the caller when `control_flow` is set to `ControlFlow::Exit`.
+    /// and returns control flow to the caller when `control_flow` is set to [`ControlFlow::Exit`].
     ///
     /// # Caveats
+    ///
     /// Despite its appearance at first glance, this is *not* a perfect replacement for
     /// `poll_events`. For example, this function will not return on Windows or macOS while a
     /// window is getting resized, resulting in all application logic outside of the

src/platform/unix.rs

@@ -35,13 +35,13 @@ pub use crate::platform_impl::{x11::util::WindowType as XWindowType, XNotSupport
 #[cfg(feature = "wayland")]
 pub use crate::window::Theme;
 
-/// Additional methods on `EventLoopWindowTarget` that are specific to Unix.
+/// Additional methods on [`EventLoopWindowTarget`] that are specific to Unix.
 pub trait EventLoopWindowTargetExtUnix {
-    /// True if the `EventLoopWindowTarget` uses Wayland.
+    /// True if the [`EventLoopWindowTarget`] uses Wayland.
     #[cfg(feature = "wayland")]
     fn is_wayland(&self) -> bool;
 
-    /// True if the `EventLoopWindowTarget` uses X11.
+    /// True if the [`EventLoopWindowTarget`] uses X11.
     #[cfg(feature = "x11")]
     fn is_x11(&self) -> bool;
 
@@ -50,11 +50,13 @@ pub trait EventLoopWindowTargetExtUnix {
     fn xlib_xconnection(&self) -> Option<Arc<XConnection>>;
 
     /// Returns a pointer to the `wl_display` object of wayland that is used by this
-    /// `EventLoopWindowTarget`.
+    /// [`EventLoopWindowTarget`].
     ///
-    /// Returns `None` if the `EventLoop` doesn't use wayland (if it uses xlib for example).
+    /// Returns `None` if the [`EventLoop`] doesn't use wayland (if it uses xlib for example).
     ///
-    /// The pointer will become invalid when the winit `EventLoop` is destroyed.
+    /// The pointer will become invalid when the winit [`EventLoop`] is destroyed.
+    ///
+    /// [`EventLoop`]: crate::event_loop::EventLoop
     #[cfg(feature = "wayland")]
     fn wayland_display(&self) -> Option<*mut raw::c_void>;
 }
@@ -134,9 +136,9 @@ impl<T> EventLoopBuilderExtUnix for EventLoopBuilder<T> {
     }
 }
 
-/// Additional methods on `Window` that are specific to Unix.
+/// Additional methods on [`Window`] that are specific to Unix.
 pub trait WindowExtUnix {
-    /// Returns the ID of the `Window` xlib object that is used by this window.
+    /// Returns the ID of the [`Window`] xlib object that is used by this window.
     ///
     /// Returns `None` if the window doesn't use xlib (if it uses wayland for example).
     #[cfg(feature = "x11")]
@@ -146,7 +148,7 @@ pub trait WindowExtUnix {
     ///
     /// Returns `None` if the window doesn't use xlib (if it uses wayland for example).
     ///
-    /// The pointer will become invalid when the glutin `Window` is destroyed.
+    /// The pointer will become invalid when the [`Window`] is destroyed.
     #[cfg(feature = "x11")]
     fn xlib_display(&self) -> Option<*mut raw::c_void>;
 
@@ -161,7 +163,7 @@ pub trait WindowExtUnix {
     ///
     /// Returns `None` if the window doesn't use xlib (if it uses wayland for example).
     ///
-    /// The pointer will become invalid when the glutin `Window` is destroyed.
+    /// The pointer will become invalid when the [`Window`] is destroyed.
     #[cfg(feature = "x11")]
     fn xcb_connection(&self) -> Option<*mut raw::c_void>;
 
@@ -169,7 +171,7 @@ pub trait WindowExtUnix {
     ///
     /// Returns `None` if the window doesn't use wayland (if it uses xlib for example).
     ///
-    /// The pointer will become invalid when the glutin `Window` is destroyed.
+    /// The pointer will become invalid when the [`Window`] is destroyed.
     #[cfg(feature = "wayland")]
     fn wayland_surface(&self) -> Option<*mut raw::c_void>;
 
@@ -177,7 +179,7 @@ pub trait WindowExtUnix {
     ///
     /// Returns `None` if the window doesn't use wayland (if it uses xlib for example).
     ///
-    /// The pointer will become invalid when the glutin `Window` is destroyed.
+    /// The pointer will become invalid when the [`Window`] is destroyed.
     #[cfg(feature = "wayland")]
     fn wayland_display(&self) -> Option<*mut raw::c_void>;
 
@@ -193,7 +195,7 @@ pub trait WindowExtUnix {
     /// It is a remnant of a previous implementation detail for the
     /// wayland backend, and is no longer relevant.
     ///
-    /// Always return true.
+    /// Always return `true`.
     #[deprecated]
     fn is_ready(&self) -> bool;
 }
@@ -285,7 +287,7 @@ impl WindowExtUnix for Window {
     }
 }
 
-/// Additional methods on `WindowBuilder` that are specific to Unix.
+/// Additional methods on [`WindowBuilder`] that are specific to Unix.
 pub trait WindowBuilderExtUnix {
     #[cfg(feature = "x11")]
     fn with_x11_visual<T>(self, visual_infos: *const T) -> Self;

src/platform/web.rs

@@ -1,8 +1,8 @@
 #![cfg(target_arch = "wasm32")]
 
 //! The web target does not automatically insert the canvas element object into the web page, to
-//! allow end users to determine how the page should be laid out. Use the `WindowExtWebSys` trait
+//! allow end users to determine how the page should be laid out. Use the [`WindowExtWebSys`] trait
-//! to retrieve the canvas from the Window. Alternatively, use the `WindowBuilderExtWebSys` trait
+//! to retrieve the canvas from the Window. Alternatively, use the [`WindowBuilderExtWebSys`] trait
 //! to provide your own canvas.
 
 use crate::window::WindowBuilder;

src/window.rs

@@ -1,4 +1,4 @@
-//! The `Window` struct and associated types.
+//! The [`Window`] struct and associated types.
 use std::fmt;
 
 use crate::{
@@ -61,7 +61,7 @@ impl Drop for Window {
 
 /// Identifier of a window. Unique for each window.
 ///
-/// Can be obtained with `window.id()`.
+/// Can be obtained with [`window.id()`](`Window::id`).
 ///
 /// Whenever you receive an event specific to a window, this event contains a `WindowId` which you
 /// can then compare to the ids of your windows.
@@ -69,13 +69,13 @@ impl Drop for Window {
 pub struct WindowId(pub(crate) platform_impl::WindowId);
 
 impl WindowId {
-    /// Returns a dummy `WindowId`, useful for unit testing.
+    /// Returns a dummy id, useful for unit testing.
     ///
     /// # Safety
     ///
     /// The only guarantee made about the return value of this function is that
     /// it will always be equal to itself and to future values returned by this function.
-    /// No other guarantees are made. This may be equal to a real `WindowId`.
+    /// No other guarantees are made. This may be equal to a real [`WindowId`].
     ///
     /// **Passing this into a winit function will result in undefined behavior.**
     pub const unsafe fn dummy() -> Self {
@@ -142,7 +142,7 @@ impl Default for WindowAttributes {
 }
 
 impl WindowBuilder {
-    /// Initializes a new `WindowBuilder` with default values.
+    /// Initializes a new builder with default values.
     #[inline]
     pub fn new() -> Self {
         Default::default()
@@ -153,8 +153,6 @@ impl WindowBuilder {
     /// If this is not set, some platform-specific dimensions will be used.
     ///
     /// See [`Window::set_inner_size`] for details.
-    ///
-    /// [`Window::set_inner_size`]: crate::window::Window::set_inner_size
     #[inline]
     pub fn with_inner_size<S: Into<Size>>(mut self, size: S) -> Self {
         self.window.inner_size = Some(size.into());
@@ -167,8 +165,6 @@ impl WindowBuilder {
     /// from reserved).
     ///
     /// See [`Window::set_min_inner_size`] for details.
-    ///
-    /// [`Window::set_min_inner_size`]: crate::window::Window::set_min_inner_size
     #[inline]
     pub fn with_min_inner_size<S: Into<Size>>(mut self, min_size: S) -> Self {
         self.window.min_inner_size = Some(min_size.into());
@@ -181,8 +177,6 @@ impl WindowBuilder {
     /// the primary monitor's dimensions by the platform.
     ///
     /// See [`Window::set_max_inner_size`] for details.
-    ///
-    /// [`Window::set_max_inner_size`]: crate::window::Window::set_max_inner_size
     #[inline]
     pub fn with_max_inner_size<S: Into<Size>>(mut self, max_size: S) -> Self {
         self.window.max_inner_size = Some(max_size.into());
@@ -211,8 +205,6 @@ impl WindowBuilder {
     /// - **X11**: The top left corner of the window, the window's "outer"
     ///   position.
     /// - **Others**: Ignored.
-    ///
-    /// [`Window::set_outer_position`]: crate::window::Window::set_outer_position
     #[inline]
     pub fn with_position<P: Into<Position>>(mut self, position: P) -> Self {
         self.window.position = Some(position.into());
@@ -224,8 +216,6 @@ impl WindowBuilder {
     /// The default is `true`.
     ///
     /// See [`Window::set_resizable`] for details.
-    ///
-    /// [`Window::set_resizable`]: crate::window::Window::set_resizable
     #[inline]
     pub fn with_resizable(mut self, resizable: bool) -> Self {
         self.window.resizable = resizable;
@@ -237,8 +227,6 @@ impl WindowBuilder {
     /// The default is `"winit window"`.
     ///
     /// See [`Window::set_title`] for details.
-    ///
-    /// [`Window::set_title`]: crate::window::Window::set_title
     #[inline]
     pub fn with_title<T: Into<String>>(mut self, title: T) -> Self {
         self.window.title = title.into();
@@ -250,8 +238,6 @@ impl WindowBuilder {
     /// The default is `None`.
     ///
     /// See [`Window::set_fullscreen`] for details.
-    ///
-    /// [`Window::set_fullscreen`]: crate::window::Window::set_fullscreen
     #[inline]
     pub fn with_fullscreen(mut self, fullscreen: Option<Fullscreen>) -> Self {
         self.window.fullscreen = fullscreen;
@@ -263,8 +249,6 @@ impl WindowBuilder {
     /// The default is `false`.
     ///
     /// See [`Window::set_maximized`] for details.
-    ///
-    /// [`Window::set_maximized`]: crate::window::Window::set_maximized
     #[inline]
     pub fn with_maximized(mut self, maximized: bool) -> Self {
         self.window.maximized = maximized;
@@ -276,8 +260,6 @@ impl WindowBuilder {
     /// The default is to show the window.
     ///
     /// See [`Window::set_visible`] for details.
-    ///
-    /// [`Window::set_visible`]: crate::window::Window::set_visible
     #[inline]
     pub fn with_visible(mut self, visible: bool) -> Self {
         self.window.visible = visible;
@@ -301,8 +283,6 @@ impl WindowBuilder {
     /// The default is `true`.
     ///
     /// See [`Window::set_decorations`] for details.
-    ///
-    /// [`Window::set_decorations`]: crate::window::Window::set_decorations
     #[inline]
     pub fn with_decorations(mut self, decorations: bool) -> Self {
         self.window.decorations = decorations;
@@ -314,8 +294,6 @@ impl WindowBuilder {
     /// The default is `false`.
     ///
     /// See [`Window::set_always_on_top`] for details.
-    ///
-    /// [`Window::set_always_on_top`]: crate::window::Window::set_always_on_top
     #[inline]
     pub fn with_always_on_top(mut self, always_on_top: bool) -> Self {
         self.window.always_on_top = always_on_top;
@@ -327,8 +305,6 @@ impl WindowBuilder {
     /// The default is `None`.
     ///
     /// See [`Window::set_window_icon`] for details.
-    ///
-    /// [`Window::set_window_icon`]: crate::window::Window::set_window_icon
     #[inline]
     pub fn with_window_icon(mut self, window_icon: Option<Icon>) -> Self {
         self.window.window_icon = window_icon;
@@ -369,7 +345,7 @@ impl Window {
     /// - **Web**: The window is created but not inserted into the web page automatically. Please
     ///   see the web platform module for more information.
     ///
-    /// [`WindowBuilder::new().build(event_loop)`]: crate::window::WindowBuilder::build
+    /// [`WindowBuilder::new().build(event_loop)`]: WindowBuilder::build
     #[inline]
     pub fn new<T: 'static>(event_loop: &EventLoopWindowTarget<T>) -> Result<Window, OsError> {
         let builder = WindowBuilder::new();
@@ -387,7 +363,7 @@ impl Window {
     /// See the [`dpi`](crate::dpi) module for more information.
     ///
     /// Note that this value can change depending on user action (for example if the window is
-    /// moved to another screen); as such, tracking `WindowEvent::ScaleFactorChanged` events is
+    /// moved to another screen); as such, tracking [`WindowEvent::ScaleFactorChanged`] events is
     /// the most robust way to track the DPI you need to use to draw.
     ///
     /// ## Platform-specific
@@ -397,19 +373,20 @@ impl Window {
     /// - **iOS:** Can only be called on the main thread. Returns the underlying `UIView`'s
     ///   [`contentScaleFactor`].
     ///
+    /// [`WindowEvent::ScaleFactorChanged`]: crate::event::WindowEvent::ScaleFactorChanged
     /// [`contentScaleFactor`]: https://developer.apple.com/documentation/uikit/uiview/1622657-contentscalefactor?language=objc
     #[inline]
     pub fn scale_factor(&self) -> f64 {
         self.window.scale_factor()
     }
 
-    /// Emits a `WindowEvent::RedrawRequested` event in the associated event loop after all OS
+    /// Emits a [`Event::RedrawRequested`] event in the associated event loop after all OS
     /// events have been processed by the event loop.
     ///
     /// This is the **strongly encouraged** method of redrawing windows, as it can integrate with
     /// OS-requested redraws (e.g. when a window gets resized).
     ///
-    /// This function can cause `RedrawRequested` events to be emitted after `Event::MainEventsCleared`
+    /// This function can cause `RedrawRequested` events to be emitted after [`Event::MainEventsCleared`]
     /// but before `Event::NewEvents` if called in the following circumstances:
     /// * While processing `MainEventsCleared`.
     /// * While processing a `RedrawRequested` event that was sent during `MainEventsCleared` or any
@@ -419,6 +396,9 @@ impl Window {
     ///
     /// - **iOS:** Can only be called on the main thread.
     /// - **Android:** Subsequent calls after `MainEventsCleared` are not handled.
+    ///
+    /// [`Event::RedrawRequested`]: crate::event::Event::RedrawRequested
+    /// [`Event::MainEventsCleared`]: crate::event::Event::MainEventsCleared
     #[inline]
     pub fn request_redraw(&self) {
         self.window.request_redraw()
@@ -430,14 +410,14 @@ impl Window {
     /// Returns the position of the top-left hand corner of the window's client area relative to the
     /// top-left hand corner of the desktop.
     ///
-    /// The same conditions that apply to `outer_position` apply to this method.
+    /// The same conditions that apply to [`Window::outer_position`] apply to this method.
     ///
     /// ## Platform-specific
     ///
     /// - **iOS:** Can only be called on the main thread. Returns the top left coordinates of the
     ///   window's [safe area] in the screen space coordinate system.
     /// - **Web:** Returns the top-left coordinates relative to the viewport. _Note: this returns the
-    ///    same value as `outer_position`._
+    ///    same value as [`Window::outer_position`]._
     /// - **Android / Wayland:** Always returns [`NotSupportedError`].
     ///
     /// [safe area]: https://developer.apple.com/documentation/uikit/uiview/2891103-safeareainsets?language=objc
@@ -469,8 +449,8 @@ impl Window {
 
     /// Modifies the position of the window.
     ///
-    /// See `outer_position` for more information about the coordinates. This automatically un-maximizes the
+    /// See [`Window::outer_position`] for more information about the coordinates.
-    /// window if it's maximized.
+    /// This automatically un-maximizes the window if it's maximized.
     ///
     /// ```no_run
     /// # use winit::dpi::{LogicalPosition, PhysicalPosition};
@@ -514,8 +494,8 @@ impl Window {
 
     /// Modifies the inner size of the window.
     ///
-    /// See `inner_size` for more information about the values. This automatically un-maximizes the
+    /// See [`Window::inner_size`] for more information about the values.
-    /// window if it's maximized.
+    /// This automatically un-maximizes the window if it's maximized.
     ///
     /// ```no_run
     /// # use winit::dpi::{LogicalSize, PhysicalSize};
@@ -542,14 +522,14 @@ impl Window {
     /// Returns the physical size of the entire window.
     ///
     /// These dimensions include the title bar and borders. If you don't want that (and you usually don't),
-    /// use `inner_size` instead.
+    /// use [`Window::inner_size`] instead.
     ///
     /// ## Platform-specific
     ///
-    /// - **iOS:** Can only be called on the main thread. Returns the `PhysicalSize` of the window in
+    /// - **iOS:** Can only be called on the main thread. Returns the [`PhysicalSize`] of the window in
     ///   screen space coordinates.
     /// - **Web:** Returns the size of the canvas element. _Note: this returns the same value as
-    ///   `inner_size`._
+    ///   [`Window::inner_size`]._
     #[inline]
     pub fn outer_size(&self) -> PhysicalSize<u32> {
         self.window.outer_size()
@@ -617,6 +597,7 @@ impl Window {
     /// Modifies the window's visibility.
     ///
     /// If `false`, this will hide the window. If `true`, this will show the window.
+    ///
     /// ## Platform-specific
     ///
     /// - **Android / Wayland / Web:** Unsupported.
@@ -628,7 +609,7 @@ impl Window {
 
     /// Gets the window's current vibility state.
     ///
-    /// If `None` means it couldn't be determined so it is not recommended to use this to drive your rendering backend.
+    /// `None` means it couldn't be determined, so it is not recommended to use this to drive your rendering backend.
     ///
     /// ## Platform-specific
     ///
@@ -641,9 +622,9 @@ impl Window {
 
     /// Sets whether the window is resizable or not.
     ///
-    /// Note that making the window unresizable doesn't exempt you from handling `Resized`, as that
+    /// Note that making the window unresizable doesn't exempt you from handling [`WindowEvent::Resized`], as that
     /// event can still be triggered by DPI scaling, entering fullscreen mode, etc. Also, the
-    /// window could still be resized by calling `[Window::set_inner_size]`.
+    /// window could still be resized by calling [`Window::set_inner_size`].
     ///
     /// ## Platform-specific
     ///
@@ -654,6 +635,8 @@ impl Window {
     /// ## Platform-specific
     ///
     /// - **iOS / Android / Web:** Unsupported.
+    ///
+    /// [`WindowEvent::Resized`]: crate::event::WindowEvent::Resized
     #[inline]
     pub fn set_resizable(&self, resizable: bool) {
         self.window.set_resizable(resizable)
@@ -705,18 +688,18 @@ impl Window {
     ///
     /// ## Platform-specific
     ///
-    /// - **macOS:** `Fullscreen::Exclusive` provides true exclusive mode with a
+    /// - **macOS:** [`Fullscreen::Exclusive`] provides true exclusive mode with a
     ///   video mode change. *Caveat!* macOS doesn't provide task switching (or
     ///   spaces!) while in exclusive fullscreen mode. This mode should be used
     ///   when a video mode change is desired, but for a better user experience,
     ///   borderless fullscreen might be preferred.
     ///
-    ///   `Fullscreen::Borderless` provides a borderless fullscreen window on a
+    ///   [`Fullscreen::Borderless`] provides a borderless fullscreen window on a
     ///   separate space. This is the idiomatic way for fullscreen games to work
     ///   on macOS. See `WindowExtMacOs::set_simple_fullscreen` if
     ///   separate spaces are not preferred.
     ///
-    ///   The dock and the menu bar are always disabled in fullscreen mode.
+    ///   The dock and the menu bar are disabled in exclusive fullscreen mode.
     /// - **iOS:** Can only be called on the main thread.
     /// - **Wayland:** Does not support exclusive fullscreen mode and will no-op a request.
     /// - **Windows:** Screen saver is disabled in fullscreen mode.
@@ -743,8 +726,6 @@ impl Window {
     /// ## Platform-specific
     ///
     /// - **iOS / Android / Web:** Unsupported.
-    ///
-    /// [`setPrefersStatusBarHidden`]: https://developer.apple.com/documentation/uikit/uiviewcontroller/1621440-prefersstatusbarhidden?language=objc
     #[inline]
     pub fn set_decorations(&self, decorations: bool) {
         self.window.set_decorations(decorations)
@@ -771,17 +752,19 @@ impl Window {
         self.window.set_always_on_top(always_on_top)
     }
 
-    /// Sets the window icon. On Windows and X11, this is typically the small icon in the top-left
+    /// Sets the window icon.
+    ///
+    /// On Windows and X11, this is typically the small icon in the top-left
     /// corner of the titlebar.
     ///
     /// ## Platform-specific
     ///
     /// - **iOS / Android / Web / Wayland / macOS:** Unsupported.
     ///
-    /// On Windows, this sets `ICON_SMALL`. The base size for a window icon is 16x16, but it's
+    /// - **Windows:** Sets `ICON_SMALL`. The base size for a window icon is 16x16, but it's
     ///   recommended to account for screen scaling and pick a multiple of that, i.e. 32x32.
     ///
-    /// X11 has no universal guidelines for icon sizes, so you're at the whims of the WM. That
+    /// - **X11:** Has no universal guidelines for icon sizes, so you're at the whims of the WM. That
     ///   said, it's usually in the same ballpark as on Windows.
     #[inline]
     pub fn set_window_icon(&self, window_icon: Option<Icon>) {
@@ -865,7 +848,7 @@ impl Window {
 
     /// Requests user attention to the window, this has no effect if the application
     /// is already focused. How requesting for user attention manifests is platform dependent,
-    /// see `UserAttentionType` for details.
+    /// see [`UserAttentionType`] for details.
     ///
     /// Providing `None` will unset the request for user attention. Unsetting the request for
     /// user attention might not be done automatically by the WM when the window receives input.
@@ -994,11 +977,13 @@ impl Window {
 
     /// Returns the list of all the monitors available on the system.
     ///
-    /// This is the same as `EventLoopWindowTarget::available_monitors`, and is provided for convenience.
+    /// This is the same as [`EventLoopWindowTarget::available_monitors`], and is provided for convenience.
     ///
     /// ## Platform-specific
     ///
     /// **iOS:** Can only be called on the main thread.
+    ///
+    /// [`EventLoopWindowTarget::available_monitors`]: crate::event_loop::EventLoopWindowTarget::available_monitors
     #[inline]
     pub fn available_monitors(&self) -> impl Iterator<Item = MonitorHandle> {
         self.window
@@ -1011,12 +996,14 @@ impl Window {
     ///
     /// Returns `None` if it can't identify any monitor as a primary one.
     ///
-    /// This is the same as `EventLoopWindowTarget::primary_monitor`, and is provided for convenience.
+    /// This is the same as [`EventLoopWindowTarget::primary_monitor`], and is provided for convenience.
     ///
     /// ## Platform-specific
     ///
     /// **iOS:** Can only be called on the main thread.
     /// **Wayland:** Always returns `None`.
+    ///
+    /// [`EventLoopWindowTarget::primary_monitor`]: crate::event_loop::EventLoopWindowTarget::primary_monitor
     #[inline]
     pub fn primary_monitor(&self) -> Option<MonitorHandle> {
         self.window.primary_monitor()
@@ -1024,7 +1011,7 @@ impl Window {
 }
 
 unsafe impl raw_window_handle::HasRawWindowHandle for Window {
-    /// Returns a `raw_window_handle::RawWindowHandle` for the Window
+    /// Returns a [`raw_window_handle::RawWindowHandle`] for the Window
     ///
     /// ## Platform-specific
     ///
@@ -1117,7 +1104,10 @@ pub enum Theme {
 
 /// ## Platform-specific
 ///
-/// - **X11:** Sets the WM's `XUrgencyHint`. No distinction between `Critical` and `Informational`.
+/// - **X11:** Sets the WM's `XUrgencyHint`. No distinction between [`Critical`] and [`Informational`].
+///
+/// [`Critical`]: Self::Critical
+/// [`Informational`]: Self::Informational
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum UserAttentionType {
     /// ## Platform-specific