Skip to content

Commit 42e8a0d

Browse files
OsspialOsspial
committed
Improve documentation
1 parent 4377680 commit 42e8a0d

File tree

9 files changed

+104
-39
lines changed

9 files changed

+104
-39
lines changed

‎examples/window_icon.rs‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,10 @@ extern crate image;
88

99
#[cfg(feature = "icon_loading")]
1010
fn main() {
11-
<<<<<<< HEAD
12-
use winit::Icon;
13-
=======
1411
use winit::window::{WindowBuilder, Icon};
1512
use winit::event::Event;
1613
use winit::event_loop::{EventLoop, ControlFlow};
1714

18-
>>>>>>> Re-organize into module structure
1915
// You'll have to choose an icon size at your own discretion. On X11, the desired size varies
2016
// by WM, and on Windows, you still have to account for screen scaling. Here we use 32px,
2117
// since it seems to work well enough in most cases. Be careful about going too high, or

‎src/dpi.rs‎

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

‎src/event.rs‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
//! The `Event` enum and assorted supporting types.
2+
//!
3+
//! These are sent to the closure given to [`EventLoop::run(...)`][event_loop_run], where they get
4+
//! processed and used to modify the program state. For more details, see the root-level documentation.
5+
//!
6+
//! [event_loop_run]: ../event_loop/struct.EventLoop.html#method.run
17
use std::time::Instant;
28
use std::path::PathBuf;
39

@@ -8,14 +14,17 @@ use platform_impl;
814
/// Describes a generic event.
915
#[derive(Clone, Debug, PartialEq)]
1016
pub enum Event<T> {
17+
/// Emitted when the OS sends an event to a winit window.
1118
WindowEvent {
1219
window_id: WindowId,
1320
event: WindowEvent,
1421
},
22+
/// Emitted when the OS sends an event to a device.
1523
DeviceEvent {
1624
device_id: DeviceId,
1725
event: DeviceEvent,
1826
},
27+
/// Emitted when an event is sent from [`EventLoopProxy::send_event`](../event_loop/struct.EventLoopProxy.html#method.send_event)
1928
UserEvent(T),
2029
/// Emitted when new events arrive from the OS to be processed.
2130
NewEvents(StartCause),
@@ -27,7 +36,7 @@ pub enum Event<T> {
2736
/// emitted, it is guaranteed to be the last event emitted.
2837
LoopDestroyed,
2938

30-
/// The application has been suspended or resumed.
39+
/// Emitted when the application has been suspended or resumed.
3140
///
3241
/// The parameter is true if app was suspended, and false if it has been resumed.
3342
Suspended(bool),
@@ -48,6 +57,7 @@ impl<T> Event<T> {
4857
}
4958
}
5059

60+
/// Describes the reason the event loop is resuming.
5161
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
5262
pub enum StartCause {
5363
/// Sent if the time specified by `ControlFlow::WaitUntil` has been reached. Contains the

‎src/event_loop.rs‎

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
//! The `EventLoop` struct and assorted supporting types, including `ControlFlow`.
2+
//!
3+
//! If you want to send custom events to the event loop, use [`EventLoop::create_proxy()`][create_proxy]
4+
//! to acquire an [`EventLoopProxy`][event_loop_proxy] and call its [`send_event`][send_event] method.
5+
//!
6+
//! See the root-level documentation for information on how to create and use an event loop to
7+
//! handle events.
8+
//!
9+
//! [create_proxy]: ./struct.EventLoop.html#method.create_proxy
10+
//! [event_loop_proxy]: ./struct.EventLoopProxy.html
11+
//! [send_event]: ./struct.EventLoopProxy.html#method.send_event
112
use std::{fmt, error};
213
use std::time::Instant;
314

@@ -29,9 +40,12 @@ impl<T> std::fmt::Debug for EventLoop<T> {
2940
}
3041
}
3142

32-
/// Returned by the user callback given to the `EventLoop::run_forever` method.
43+
/// Set by the user callback given to the `EventLoop::run` method.
3344
///
34-
/// Indicates whether the `run_forever` method should continue or complete.
45+
/// Indicates the desired behavior of the event loop after [`Event::EventsCleared`][events_cleared]
46+
/// is emitted.
47+
///
48+
/// [events_cleared]: ../event/enum.Event.html#variant.EventsCleared
3549
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
3650
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
3751
pub enum ControlFlow {
@@ -43,7 +57,8 @@ pub enum ControlFlow {
4357
/// When the current loop iteration finishes, immediately begin a new iteration regardless of
4458
/// whether or not new events are available to process.
4559
Poll,
46-
/// Send a `LoopDestroyed` event and stop the event loop.
60+
/// Send a `LoopDestroyed` event and stop the event loop. Once set, `control_flow` cannot be
61+
/// changed from `Exit`.
4762
Exit
4863
}
4964

@@ -55,13 +70,14 @@ impl Default for ControlFlow {
5570
}
5671

5772
impl EventLoop<()> {
73+
/// Builds a new event loop with a `()` as the user event type.
5874
pub fn new() -> EventLoop<()> {
5975
EventLoop::<()>::new_user_event()
6076
}
6177
}
6278

6379
impl<T> EventLoop<T> {
64-
/// Builds a new events loop.
80+
/// Builds a new event loop.
6581
///
6682
/// Usage will result in display backend initialisation, this can be controlled on linux
6783
/// using an environment variable `WINIT_UNIX_BACKEND`. Legal values are `x11` and `wayland`.
@@ -109,7 +125,7 @@ impl<T> EventLoop<T> {
109125
}
110126
}
111127

112-
/// Used to wake up the `EventLoop` from another thread.
128+
/// Used to send custom events to `EventLoop`.
113129
#[derive(Clone)]
114130
pub struct EventLoopProxy<T> {
115131
events_loop_proxy: platform_impl::EventLoopProxy<T>,

‎src/lib.rs‎

Lines changed: 36 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -2,34 +2,35 @@
22
//!
33
//! # Building a window
44
//!
5-
//! Before you can build a window, you first need to build an `EventLoop`. This is done with the
6-
//! `EventLoop::new()` function. Example:
5+
//! Before you can build a [`Window`], you first need to build an [`EventLoop`]. This is done with the
6+
//! [`EventLoop::new()`] function.
77
//!
88
//! ```no_run
99
//! use winit::event_loop::EventLoop;
1010
//! let events_loop = EventLoop::new();
1111
//! ```
1212
//!
13-
//! Once this is done there are two ways to create a window:
13+
//! Once this is done there are two ways to create a [`Window`]:
1414
//!
15-
//! - Calling `Window::new(&events_loop)`.
16-
//! - Calling `let builder = WindowBuilder::new()` then `builder.build(&events_loop)`.
15+
//! - Calling [`Window::new(&events_loop)`][window_new].
16+
//! - Calling [`let builder = WindowBuilder::new()`][window_builder_new] then [`builder.build(&events_loop)`][window_builder_build].
1717
//!
1818
//! The first way is the simplest way and will give you default values for everything.
1919
//!
20-
//! The second way allows you to customize the way your window will look and behave by modifying
21-
//! the fields of the `WindowBuilder` object before you create the window.
20+
//! The second way allows you to customize the way your [`Window`] will look and behave by modifying
21+
//! the fields of the [`WindowBuilder`] object before you create the [`Window`].
2222
//!
23-
//! # Events handling
23+
//! # Event handling
2424
//!
25-
//! Once a window has been created, it will *generate events*. For example whenever the user moves
26-
//! the window, resizes the window, moves the mouse, etc. an event is generated.
25+
//! Once a [`Window`] has been created, it will *generate events*. For example whenever the user moves
26+
//! the [`Window`], resizes the [`Window`], moves the mouse, etc. an event is generated.
2727
//!
28-
//! The events generated by a window can be retreived from the `EventLoop` the window was created
28+
//! The events generated by a [`Window`] can be retreived from the [`EventLoop`] the [`Window`] was created
2929
//! with.
3030
//!
31-
//! You do this by calling `events_loop.run(...)`. This function will run forever unless it is
32-
//! stopped by returning `ControlFlow::Exit`, at which point the entire program will terminate.
31+
//! You do this by calling [`events_loop.run(...)`][event_loop_run]. This function will run forever
32+
//! unless `control_flow` is set to [`ControlFlow`]`::`[`Exit`], at which point [`Event`]`::`[`LoopDestroyed`]
33+
//! is emitted and the entire program terminates.
3334
//!
3435
//! ```no_run
3536
//! use winit::event_loop::ControlFlow;
@@ -48,16 +49,31 @@
4849
//! });
4950
//! ```
5051
//!
51-
//! If you use multiple windows, the `WindowEvent` event has a member named `window_id`. You can
52-
//! compare it with the value returned by the `id()` method of `Window` in order to know which
53-
//! window has received the event.
52+
//! If you use multiple [`Window`]s, [`Event`]`::`[`WindowEvent`] has a member named `window_id`. You can
53+
//! compare it with the value returned by the [`id()`][window_id_fn] method of [`Window`] in order to know which
54+
//! [`Window`] has received the event.
5455
//!
5556
//! # Drawing on the window
5657
//!
57-
//! Winit doesn't provide any function that allows drawing on a window. However it allows you to
58-
//! retrieve the raw handle of the window (see the `platform` module for that), which in turn allows you
59-
//! to create an OpenGL/Vulkan/DirectX/Metal/etc. context that will draw on the window.
60-
//!
58+
//! Winit doesn't provide any function that allows drawing on a [`Window`]. However it allows you to
59+
//! retrieve the raw handle of the window (see the [`platform`] module), which in turn allows you
60+
//! to create an OpenGL/Vulkan/DirectX/Metal/etc. context that will draw on the [`Window`].
61+
//!
62+
//! [`EventLoop`]: ./event_loop/struct.EventLoop.html
63+
//! [`EventLoop::new()`]: ./event_loop/struct.EventLoop.html#method.new
64+
//! [event_loop_run]: ./event_loop/struct.EventLoop.html#method.run
65+
//! [`ControlFlow`]: ./event_loop/enum.ControlFlow.html
66+
//! [`Exit`]: ./event_loop/enum.ControlFlow.html#variant.Exit
67+
//! [`Window`]: ./window/struct.Window.html
68+
//! [`WindowBuilder`]: ./window/struct.WindowBuilder.html
69+
//! [window_new]: ./window/struct.Window.html#method.new
70+
//! [window_builder_new]: ./window/struct.WindowBuilder.html#method.new
71+
//! [window_builder_build]: ./window/struct.WindowBuilder.html#method.build
72+
//! [window_id_fn]: ./window/struct.Window.html#method.id
73+
//! [`Event`]: ./event/enum.Event.html
74+
//! [`WindowEvent`]: ./event/enum.Event.html#variant.WindowEvent
75+
//! [`LoopDestroyed`]: ./event/enum.Event.html#variant.LoopDestroyed
76+
//! [`platform`]: ./platform/index.html
6177
6278
#[allow(unused_imports)]
6379
#[macro_use]

‎src/monitor.rs‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,28 @@
1+
//! Types useful for interacting with a user's monitors.
2+
//!
3+
//! If you want to get basic information about a monitor, you can use the [`MonitorId`][monitor_id]
4+
//! type. This is retreived from an [`AvailableMonitorsIter`][monitor_iter], which can be acquired
5+
//! with:
6+
//! - [`EventLoop::get_available_monitors`][loop_get]
7+
//! - [`Window::get_available_monitors`][window_get].
8+
//!
9+
//! [monitor_id]: ./struct.MonitorId.html
10+
//! [monitor_iter]: ./struct.AvailableMonitorsIter.html
11+
//! [loop_get]: ../event_loop/struct.EventLoop.html#method.get_available_monitors
12+
//! [window_get]: ../window/struct.Window.html#method.get_available_monitors
113
use std::collections::vec_deque::IntoIter as VecDequeIter;
214

315
use platform_impl;
416
use dpi::{PhysicalPosition, PhysicalSize};
517

6-
/// An iterator for the list of available monitors.
18+
/// An iterator over all available monitors.
19+
///
20+
/// Can be acquired with:
21+
/// - [`EventLoop::get_available_monitors`][loop_get]
22+
/// - [`Window::get_available_monitors`][window_get].
23+
///
24+
/// [loop_get]: ../event_loop/struct.EventLoop.html#method.get_available_monitors
25+
/// [window_get]: ../window/struct.Window.html#method.get_available_monitors
726
// Implementation note: we retrieve the list once, then serve each element by one by one.
827
// This may change in the future.
928
#[derive(Debug)]

‎src/platform/desktop.rs‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,13 @@ use event_loop::{EventLoop, ControlFlow};
99

1010
/// Additional methods on `EventLoop` that are specific to desktop platforms.
1111
pub trait EventLoopExtDesktop {
12+
/// A type provided by the user that can be passed through `Event::UserEvent`.
1213
type UserEvent;
14+
1315
/// Initializes the `winit` event loop.
1416
///
15-
/// Unlikes `run`, this function *does* return control flow to the caller when `control_flow`
16-
/// is set to `ControlFlow::Exit`.
17+
/// Unlikes `run`, this function accepts non-`'static` closures and returns control flow to the
18+
/// caller when `control_flow` is set to `ControlFlow::Exit`.
1719
fn run_return<F>(&mut self, event_handler: F)
1820
where F: FnMut(Event<Self::UserEvent>, &EventLoop<Self::UserEvent>, &mut ControlFlow);
1921
}

‎src/platform/mod.rs‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,19 @@
11
//! Contains traits with platform-specific methods in them.
22
//!
3-
//! Contains the follow modules:
3+
//! Contains the follow OS-specific modules:
44
//!
55
//! - `android`
66
//! - `ios`
77
//! - `macos`
88
//! - `unix`
99
//! - `windows`
1010
//!
11-
//! However only the module corresponding to the platform you're compiling to will be available.
11+
//! And the following platform-specific module:
12+
//!
13+
//! - `desktop` (available on `windows`, `unix`, and `macos`)
1214
//!
15+
//! However only the module corresponding to the platform you're compiling to will be available.
16+
1317
pub mod android;
1418
pub mod ios;
1519
pub mod macos;

‎src/window.rs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
//! The `Window` struct and associated types.
12
use std::{fmt, error};
23

34
use platform_impl;
@@ -578,6 +579,7 @@ impl Window {
578579
MonitorId { inner: self.window.get_primary_monitor() }
579580
}
580581

582+
/// Returns an identifier unique to the window.
581583
#[inline]
582584
pub fn id(&self) -> WindowId {
583585
WindowId(self.window.id())

0 commit comments

Comments
 (0)