Improve documentation

examples/window_icon.rs

@@ -8,14 +8,10 @@ extern crate image;
 
 #[cfg(feature = "icon_loading")]
 fn main() {
-<<<<<<< HEAD
-    use winit::Icon;
-=======
     use winit::window::{WindowBuilder, Icon};
     use winit::event::Event;
     use winit::event_loop::{EventLoop, ControlFlow};
 
->>>>>>> Re-organize into module structure
     // You'll have to choose an icon size at your own discretion. On X11, the desired size varies
     // by WM, and on Windows, you still have to account for screen scaling. Here we use 32px,
     // since it seems to work well enough in most cases. Be careful about going too high, or

src/dpi.rs

@@ -33,9 +33,9 @@
 //!   windows. This event is sent any time the DPI factor changes, either because the window moved to another monitor,
 //!   or because the user changed the configuration of their screen.
 //! - You can also retrieve the DPI factor of a monitor by calling
-//!   [`MonitorId::get_hidpi_factor`](../struct.MonitorId.html#method.get_hidpi_factor), or the
+//!   [`MonitorId::get_hidpi_factor`](../monitor/struct.MonitorId.html#method.get_hidpi_factor), or the
 //!   current DPI factor applied to a window by calling
-//!   [`Window::get_hidpi_factor`](../struct.Window.html#method.get_hidpi_factor), which is roughly equivalent
+//!   [`Window::get_hidpi_factor`](../window/struct.Window.html#method.get_hidpi_factor), which is roughly equivalent
 //!   to `window.get_current_monitor().get_hidpi_factor()`.
 //!
 //! Depending on the platform, the window's actual DPI factor may only be known after
@@ -59,9 +59,9 @@
 //!
 //! The window's logical size is conserved across DPI changes, resulting in the physical size changing instead. This
 //! may be surprising on X11, but is quite standard elsewhere. Physical size changes always produce a
-//! [`Resized`](../enum.WindowEvent.html#variant.Resized) event, even on platforms where no resize actually occurs,
+//! [`Resized`](../event/enum.WindowEvent.html#variant.Resized) event, even on platforms where no resize actually occurs,
 //! such as macOS and Wayland. As a result, it's not necessary to separately handle
-//! [`HiDpiFactorChanged`](../enum.WindowEvent.html#variant.HiDpiFactorChanged) if you're only listening for size.
+//! [`HiDpiFactorChanged`](../event/enum.WindowEvent.html#variant.HiDpiFactorChanged) if you're only listening for size.
 //!
 //! Your GPU has no awareness of the concept of logical pixels, and unless you like wasting pixel density, your
 //! framebuffer's size should be in physical pixels.

src/event.rs

@@ -1,3 +1,9 @@
+//! The `Event` enum and assorted supporting types.
+//!
+//! These are sent to the closure given to [`EventLoop::run(...)`][event_loop_run], where they get
+//! processed and used to modify the program state. For more details, see the root-level documentation.
+//!
+//! [event_loop_run]: ../event_loop/struct.EventLoop.html#method.run
 use std::time::Instant;
 use std::path::PathBuf;
 
@@ -8,14 +14,17 @@ use platform_impl;
 /// Describes a generic event.
 #[derive(Clone, Debug, PartialEq)]
 pub enum Event<T> {
+    /// Emitted when the OS sends an event to a winit window.
     WindowEvent {
         window_id: WindowId,
         event: WindowEvent,
     },
+    /// Emitted when the OS sends an event to a device.
     DeviceEvent {
         device_id: DeviceId,
         event: DeviceEvent,
     },
+    /// Emitted when an event is sent from [`EventLoopProxy::send_event`](../event_loop/struct.EventLoopProxy.html#method.send_event)
     UserEvent(T),
     /// Emitted when new events arrive from the OS to be processed.
     NewEvents(StartCause),
@@ -27,7 +36,7 @@ pub enum Event<T> {
     /// emitted, it is guaranteed to be the last event emitted.
     LoopDestroyed,
 
-    /// The application has been suspended or resumed.
+    /// Emitted when the application has been suspended or resumed.
     ///
     /// The parameter is true if app was suspended, and false if it has been resumed.
     Suspended(bool),
@@ -48,6 +57,7 @@ impl<T> Event<T> {
     }
 }
 
+/// Describes the reason the event loop is resuming.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum StartCause {
     /// Sent if the time specified by `ControlFlow::WaitUntil` has been reached. Contains the

src/event_loop.rs

@@ -1,3 +1,14 @@
+//! 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]
+//! to acquire an [`EventLoopProxy`][event_loop_proxy] and call its [`send_event`][send_event] method.
+//!
+//! See the root-level documentation for information on how to create and use an event loop to
+//! handle events.
+//!
+//! [create_proxy]: ./struct.EventLoop.html#method.create_proxy
+//! [event_loop_proxy]: ./struct.EventLoopProxy.html
+//! [send_event]: ./struct.EventLoopProxy.html#method.send_event
 use std::{fmt, error};
 use std::time::Instant;
 
@@ -29,9 +40,12 @@ impl<T> std::fmt::Debug for EventLoop<T> {
     }
 }
 
-/// Returned by the user callback given to the `EventLoop::run_forever` method.
+/// Set by the user callback given to the `EventLoop::run` method.
 ///
-/// Indicates whether the `run_forever` method should continue or complete.
+/// Indicates the desired behavior of the event loop after [`Event::EventsCleared`][events_cleared]
+/// is emitted.
+///
+/// [events_cleared]: ../event/enum.Event.html#variant.EventsCleared
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub enum ControlFlow {
@@ -43,7 +57,8 @@ pub enum ControlFlow {
     /// When the current loop iteration finishes, immediately begin a new iteration regardless of
     /// whether or not new events are available to process.
     Poll,
-    /// Send a `LoopDestroyed` event and stop the event loop.
+    /// Send a `LoopDestroyed` event and stop the event loop. Once set, `control_flow` cannot be
+    /// changed from `Exit`.
     Exit
 }
 
@@ -55,13 +70,14 @@ impl Default for ControlFlow {
 }
 
 impl EventLoop<()> {
+    /// Builds a new event loop with a `()` as the user event type.
     pub fn new() -> EventLoop<()> {
         EventLoop::<()>::new_user_event()
     }
 }
 
 impl<T> EventLoop<T> {
-    /// Builds a new events loop.
+    /// Builds a new event loop.
     ///
     /// Usage will result in display backend initialisation, this can be controlled on linux
     /// using an environment variable `WINIT_UNIX_BACKEND`. Legal values are `x11` and `wayland`.
@@ -109,7 +125,7 @@ impl<T> EventLoop<T> {
     }
 }
 
-/// Used to wake up the `EventLoop` from another thread.
+/// Used to send custom events to `EventLoop`.
 #[derive(Clone)]
 pub struct EventLoopProxy<T> {
     events_loop_proxy: platform_impl::EventLoopProxy<T>,

src/lib.rs

@@ -2,34 +2,35 @@
 //!
 //! # Building a window
 //!
-//! Before you can build a window, you first need to build an `EventLoop`. This is done with the
-//! `EventLoop::new()` function. Example:
+//! Before you can build a [`Window`], you first need to build an [`EventLoop`]. This is done with the
+//! [`EventLoop::new()`] function.
 //!
 //! ```no_run
 //! use winit::event_loop::EventLoop;
 //! let events_loop = EventLoop::new();
 //! ```
 //!
-//! Once this is done there are two ways to create a window:
+//! Once this is done there are two ways to create a [`Window`]:
 //!
-//!  - Calling `Window::new(&events_loop)`.
-//!  - Calling `let builder = WindowBuilder::new()` then `builder.build(&events_loop)`.
+//!  - Calling [`Window::new(&events_loop)`][window_new].
+//!  - Calling [`let builder = WindowBuilder::new()`][window_builder_new] then [`builder.build(&events_loop)`][window_builder_build].
 //!
 //! The first way is the simplest way and will give you default values for everything.
 //!
-//! The second way allows you to customize the way your window will look and behave by modifying
-//! the fields of the `WindowBuilder` object before you create the window.
+//! The second way allows you to customize the way your [`Window`] will look and behave by modifying
+//! the fields of the [`WindowBuilder`] object before you create the [`Window`].
 //!
-//! # Events handling
+//! # Event handling
 //!
-//! Once a window has been created, it will *generate events*. For example whenever the user moves
-//! the window, resizes the window, moves the mouse, etc. an event is generated.
+//! Once a [`Window`] has been created, it will *generate events*. For example whenever the user moves
+//! the [`Window`], resizes the [`Window`], moves the mouse, etc. an event is generated.
 //!
-//! The events generated by a window can be retreived from the `EventLoop` the window was created
+//! The events generated by a [`Window`] can be retreived from the [`EventLoop`] the [`Window`] was created
 //! with.
 //!
-//! You do this by calling `events_loop.run(...)`. This function will run forever unless it is
-//! stopped by returning `ControlFlow::Exit`, at which point the entire program will terminate.
+//! You do this by calling [`events_loop.run(...)`][event_loop_run]. This function will run forever
+//! unless `control_flow` is set to [`ControlFlow`]`::`[`Exit`], at which point [`Event`]`::`[`LoopDestroyed`]
+//! is emitted and the entire program terminates.
 //!
 //! ```no_run
 //! use winit::event_loop::ControlFlow;
@@ -48,16 +49,31 @@
 //! });
 //! ```
 //!
-//! If you use multiple windows, the `WindowEvent` event has a member named `window_id`. You can
-//! compare it with the value returned by the `id()` method of `Window` in order to know which
-//! window has received the event.
+//! If you use multiple [`Window`]s, [`Event`]`::`[`WindowEvent`] has a member named `window_id`. You can
+//! compare it with the value returned by the [`id()`][window_id_fn] method of [`Window`] in order to know which
+//! [`Window`] has received the event.
 //!
 //! # Drawing on the window
 //!
-//! Winit doesn't provide any function that allows drawing on a window. However it allows you to
-//! retrieve the raw handle of the window (see the `platform` module for that), which in turn allows you
-//! to create an OpenGL/Vulkan/DirectX/Metal/etc. context that will draw on the window.
-//!
+//! Winit doesn't provide any function that allows drawing on a [`Window`]. However it allows you to
+//! retrieve the raw handle of the window (see the [`platform`] module), which in turn allows you
+//! to create an OpenGL/Vulkan/DirectX/Metal/etc. context that will draw on the [`Window`].
+//!
+//! [`EventLoop`]: ./event_loop/struct.EventLoop.html
+//! [`EventLoop::new()`]: ./event_loop/struct.EventLoop.html#method.new
+//! [event_loop_run]: ./event_loop/struct.EventLoop.html#method.run
+//! [`ControlFlow`]: ./event_loop/enum.ControlFlow.html
+//! [`Exit`]: ./event_loop/enum.ControlFlow.html#variant.Exit
+//! [`Window`]: ./window/struct.Window.html
+//! [`WindowBuilder`]: ./window/struct.WindowBuilder.html
+//! [window_new]: ./window/struct.Window.html#method.new
+//! [window_builder_new]: ./window/struct.WindowBuilder.html#method.new
+//! [window_builder_build]: ./window/struct.WindowBuilder.html#method.build
+//! [window_id_fn]: ./window/struct.Window.html#method.id
+//! [`Event`]: ./event/enum.Event.html
+//! [`WindowEvent`]: ./event/enum.Event.html#variant.WindowEvent
+//! [`LoopDestroyed`]: ./event/enum.Event.html#variant.LoopDestroyed
+//! [`platform`]: ./platform/index.html
 
 #[allow(unused_imports)]
 #[macro_use]

src/monitor.rs

@@ -1,9 +1,28 @@
+//! Types useful for interacting with a user's monitors.
+//!
+//! If you want to get basic information about a monitor, you can use the [`MonitorId`][monitor_id]
+//! type. This is retreived from an [`AvailableMonitorsIter`][monitor_iter], which can be acquired
+//! with:
+//! - [`EventLoop::get_available_monitors`][loop_get]
+//! - [`Window::get_available_monitors`][window_get].
+//!
+//! [monitor_id]: ./struct.MonitorId.html
+//! [monitor_iter]: ./struct.AvailableMonitorsIter.html
+//! [loop_get]: ../event_loop/struct.EventLoop.html#method.get_available_monitors
+//! [window_get]: ../window/struct.Window.html#method.get_available_monitors
 use std::collections::vec_deque::IntoIter as VecDequeIter;
 
 use platform_impl;
 use dpi::{PhysicalPosition, PhysicalSize};
 
-/// An iterator for the list of available monitors.
+/// An iterator over all available monitors.
+///
+/// Can be acquired with:
+/// - [`EventLoop::get_available_monitors`][loop_get]
+/// - [`Window::get_available_monitors`][window_get].
+///
+/// [loop_get]: ../event_loop/struct.EventLoop.html#method.get_available_monitors
+/// [window_get]: ../window/struct.Window.html#method.get_available_monitors
 // Implementation note: we retrieve the list once, then serve each element by one by one.
 // This may change in the future.
 #[derive(Debug)]

src/platform/desktop.rs

@@ -9,11 +9,13 @@ use event_loop::{EventLoop, ControlFlow};
 
 /// Additional methods on `EventLoop` that are specific to desktop platforms.
 pub trait EventLoopExtDesktop {
+    /// A type provided by the user that can be passed through `Event::UserEvent`.
     type UserEvent;
+
     /// Initializes the `winit` event loop.
     ///
-    /// Unlikes `run`, this function *does* return control flow to the caller when `control_flow`
-    /// is set to `ControlFlow::Exit`.
+    /// Unlikes `run`, this function accepts non-`'static` closures and  returns control flow to the
+    /// caller when `control_flow` is set to `ControlFlow::Exit`.
     fn run_return<F>(&mut self, event_handler: F)
         where F: FnMut(Event<Self::UserEvent>, &EventLoop<Self::UserEvent>, &mut ControlFlow);
 }

src/platform/mod.rs

@@ -1,15 +1,19 @@
 //! Contains traits with platform-specific methods in them.
 //!
-//! Contains the follow modules:
+//! Contains the follow OS-specific modules:
 //!
 //!  - `android`
 //!  - `ios`
 //!  - `macos`
 //!  - `unix`
 //!  - `windows`
 //!
-//! However only the module corresponding to the platform you're compiling to will be available.
+//! And the following platform-specific module:
+//!
+//! - `desktop` (available on `windows`, `unix`, and `macos`)
 //!
+//! However only the module corresponding to the platform you're compiling to will be available.
+
 pub mod android;
 pub mod ios;
 pub mod macos;

src/window.rs

@@ -1,3 +1,4 @@
+//! The `Window` struct and associated types.
 use std::{fmt, error};
 
 use platform_impl;
@@ -578,6 +579,7 @@ impl Window {
         MonitorId { inner: self.window.get_primary_monitor() }
     }
 
+    /// Returns an identifier unique to the window.
     #[inline]
     pub fn id(&self) -> WindowId {
         WindowId(self.window.id())