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

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,16 +89,14 @@ 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`:
-///
-///  - `with_titlebar_transparent`
-///  - `with_title_hidden`
-///  - `with_titlebar_hidden`
-///  - `with_titlebar_buttons_hidden`
-///  - `with_fullsize_content_view`
+/// **Note:** Properties dealing with the titlebar will be overwritten by the [`WindowBuilder::with_decorations`] method:
+/// - `with_titlebar_transparent`
+/// - `with_title_hidden`
+/// - `with_titlebar_hidden`
+/// - `with_titlebar_buttons_hidden`
+/// - `with_fullsize_content_view`
 pub trait WindowBuilderExtMacOS {
     /// Enables click-and-drag behavior for the entire window, not just the titlebar.
     fn with_movable_by_window_background(self, movable_by_window_background: bool)
@@ -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
-    /// control flow to the caller when `control_flow` is set to `ControlFlow::Exit`.
+    /// Unlike [`EventLoop::run`], this function accepts non-`'static` (i.e. non-`move`) closures
+    /// 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
-//! to retrieve the canvas from the Window. Alternatively, use the `WindowBuilderExtWebSys` 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 provide your own canvas.
 
 use crate::window::WindowBuilder;