Use paths for intra-doc links, and verify that links are valid in CI (#1244)

* Use paths to generate intra-doc links

* Add entry to PR checklist

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,6 +1,7 @@
 - [ ] Tested on all platforms changed
 - [ ] Compilation warnings were addressed
 - [ ] `cargo fmt` has been run on this branch
+- [ ] `cargo doc` builds successfully
 - [ ] Added an entry to `CHANGELOG.md` if knowledge of this change could be valuable to users
 - [ ] Updated documentation to reflect any user-facing changes, including notes of platform-specific behavior
 - [ ] Created or updated an example program if it would help users understand this functionality

.travis.yml

@@ -81,6 +81,8 @@ install:
 
 script:
   - cargo +stable fmt --all -- --check
+  # Ensure that the documentation builds properly.
+  - cargo doc --no-deps
   # Install cargo-web to build stdweb
   - if [[ $WEB = "web" ]]; then cargo install -f cargo-web; fi
   # Build without serde then with serde

appveyor.yml

@@ -32,3 +32,4 @@ build: false
 test_script:
   - cargo test --verbose
   - cargo test --features serde --verbose
+  - cargo doc --no-deps

src/dpi.rs

@@ -28,18 +28,18 @@
 //! them entering an existential panic. Once users enter that state, they will no longer be focused on your application.
 //!
 //! There are two ways to get the DPI factor:
-//! - You can track the [`HiDpiFactorChanged`](../enum.WindowEvent.html#variant.HiDpiFactorChanged) event of your
+//! - You can track the [`HiDpiFactorChanged`](event::WindowEvent::HiDpiFactorChanged) event of your
 //!   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
-//!   [`MonitorHandle::hidpi_factor`](../monitor/struct.MonitorHandle.html#method.hidpi_factor), or the
+//!   [`MonitorHandle::hidpi_factor`](monitor::MonitorHandle::hidpi_factor), or the
 //!   current DPI factor applied to a window by calling
-//!   [`Window::hidpi_factor`](../window/struct.Window.html#method.hidpi_factor), which is roughly equivalent
+//!   [`Window::hidpi_factor`](window::Window::hidpi_factor), which is roughly equivalent
 //!   to `window.current_monitor().hidpi_factor()`.
 //!
 //! Depending on the platform, the window's actual DPI factor may only be known after
 //! the event loop has started and your window has been drawn once. To properly handle these cases,
-//! the most robust way is to monitor the [`HiDpiFactorChanged`](../enum.WindowEvent.html#variant.HiDpiFactorChanged)
+//! the most robust way is to monitor the [`HiDpiFactorChanged`](event::WindowEvent::HiDpiFactorChanged)
 //! event and dynamically adapt your drawing logic to follow the DPI factor.
 //!
 //! Here's an overview of what sort of DPI factors you can expect, and where they come from:
@@ -59,21 +59,21 @@
 //!
 //! 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`](../event/enum.WindowEvent.html#variant.Resized) event, even on platforms where no resize actually occurs,
+//! [`Resized`](event::WindowEvent::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`](../event/enum.WindowEvent.html#variant.HiDpiFactorChanged) if you're only listening for size.
+//! [`HiDpiFactorChanged`](event::WindowEvent::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.
 //!
-//! `winit` will send [`Resized`](../enum.WindowEvent.html#variant.Resized) events whenever a window's logical size
+//! `winit` will send [`Resized`](event::WindowEvent::Resized) events whenever a window's logical size
-//! changes, and [`HiDpiFactorChanged`](../enum.WindowEvent.html#variant.HiDpiFactorChanged) events
+//! changes, and [`HiDpiFactorChanged`](event::WindowEvent::HiDpiFactorChanged) events
 //! whenever the DPI factor changes. Receiving either of these events means that the physical size of your window has
 //! changed, and you should recompute it using the latest values you received for each. If the logical size and the
 //! DPI factor change simultaneously, `winit` will send both events together; thus, it's recommended to buffer
 //! these events and process them at the end of the queue.
 //!
-//! If you never received any [`HiDpiFactorChanged`](../enum.WindowEvent.html#variant.HiDpiFactorChanged) events,
+//! If you never received any [`HiDpiFactorChanged`](event::WindowEvent::HiDpiFactorChanged) events,
 //! then your window's DPI factor is 1.
 
 /// Checks that the DPI factor is a normal positive `f64`.

src/event.rs

@@ -3,7 +3,7 @@
 //! 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
+//! [event_loop_run]: event_loop::EventLoop::run
 use instant::Instant;
 use std::path::PathBuf;
 
@@ -26,7 +26,7 @@ pub enum Event<T> {
         device_id: DeviceId,
         event: DeviceEvent,
     },
-    /// Emitted when an event is sent from [`EventLoopProxy::send_event`](../event_loop/struct.EventLoopProxy.html#method.send_event)
+    /// Emitted when an event is sent from [`EventLoopProxy::send_event`](crate::event_loop::EventLoopProxy::send_event)
     UserEvent(T),
     /// Emitted when new events arrive from the OS to be processed.
     NewEvents(StartCause),
@@ -199,7 +199,7 @@ pub enum WindowEvent {
     /// * Changing the display's DPI factor (e.g. in Control Panel on Windows).
     /// * Moving the window to a display with a different DPI factor.
     ///
-    /// For more information about DPI in general, see the [`dpi`](../dpi/index.html) module.
+    /// For more information about DPI in general, see the [`dpi`](crate::dpi) module.
     HiDpiFactorChanged(f64),
 }
 

src/event_loop.rs

@@ -6,9 +6,9 @@
 //! 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
+//! [create_proxy]: crate::event_loop::EventLoop::create_proxy
-//! [event_loop_proxy]: ./struct.EventLoopProxy.html
+//! [event_loop_proxy]: crate::event_loop::EventLoopProxy
-//! [send_event]: ./struct.EventLoopProxy.html#method.send_event
+//! [send_event]: crate::event_loop::EventLoopProxy::send_event
 use instant::Instant;
 use std::ops::Deref;
 use std::{error, fmt};
@@ -68,7 +68,7 @@ impl<T> fmt::Debug for EventLoopWindowTarget<T> {
 /// are **not** persistent between multiple calls to `run_return` - issuing a new call will reset
 /// the control flow to `Poll`.
 ///
-/// [events_cleared]: ../event/enum.Event.html#variant.EventsCleared
+/// [events_cleared]: crate::event::Event::EventsCleared
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub enum ControlFlow {
     /// When the current loop iteration finishes, immediately begin a new iteration regardless of
@@ -139,7 +139,7 @@ impl<T> EventLoop<T> {
     ///
     /// Any values not passed to this function will *not* be dropped.
     ///
-    /// [`ControlFlow`]: ./enum.ControlFlow.html
+    /// [`ControlFlow`]: crate::event_loop::ControlFlow
     #[inline]
     pub fn run<F>(self, event_handler: F) -> !
     where

src/lib.rs

@@ -92,25 +92,26 @@
 //! 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`]: event_loop::EventLoop
-//! [`EventLoop::new()`]: ./event_loop/struct.EventLoop.html#method.new
+//! [`EventLoop::new()`]: event_loop::EventLoop::new
-//! [event_loop_run]: ./event_loop/struct.EventLoop.html#method.run
+//! [event_loop_run]: event_loop::EventLoop::run
-//! [`ControlFlow`]: ./event_loop/enum.ControlFlow.html
+//! [`ControlFlow`]: event_loop::ControlFlow
-//! [`Exit`]: ./event_loop/enum.ControlFlow.html#variant.Exit
+//! [`Exit`]: event_loop::ControlFlow::Exit
-//! [`Window`]: ./window/struct.Window.html
+//! [`Window`]: window::Window
-//! [`WindowBuilder`]: ./window/struct.WindowBuilder.html
+//! [`WindowBuilder`]: window::WindowBuilder
-//! [window_new]: ./window/struct.Window.html#method.new
+//! [window_new]: window::Window::new
-//! [window_builder_new]: ./window/struct.WindowBuilder.html#method.new
+//! [window_builder_new]: window::WindowBuilder::new
-//! [window_builder_build]: ./window/struct.WindowBuilder.html#method.build
+//! [window_builder_build]: window::WindowBuilder::build
-//! [window_id_fn]: ./window/struct.Window.html#method.id
+//! [window_id_fn]: window::Window::id
-//! [`Event`]: ./event/enum.Event.html
+//! [`Event`]: event::Event
-//! [`WindowEvent`]: ./event/enum.WindowEvent.html
+//! [`WindowEvent`]: event::WindowEvent
-//! [`DeviceEvent`]: ./event/enum.DeviceEvent.html
+//! [`DeviceEvent`]: event::DeviceEvent
-//! [`UserEvent`]: ./event/enum.Event.html#variant.UserEvent
+//! [`UserEvent`]: event::Event::UserEvent
-//! [`LoopDestroyed`]: ./event/enum.Event.html#variant.LoopDestroyed
+//! [`LoopDestroyed`]: event::Event::LoopDestroyed
-//! [`platform`]: ./platform/index.html
+//! [`platform`]: platform
 
 #![deny(rust_2018_idioms)]
+#![deny(intra_doc_link_resolution_failure)]
 
 #[allow(unused_imports)]
 #[macro_use]

src/monitor.rs

@@ -1,14 +1,14 @@
 //! 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_id]
+//! If you want to get basic information about a monitor, you can use the [`MonitorHandle`][monitor_handle]
 //! type. This is retreived from one of the following methods, which return an iterator of
-//! [`MonitorHandle`][monitor_id]:
+//! [`MonitorHandle`][monitor_handle]:
 //! - [`EventLoop::available_monitors`][loop_get]
 //! - [`Window::available_monitors`][window_get].
 //!
-//! [monitor_id]: ./struct.MonitorHandle.html
+//! [monitor_handle]: crate::monitor::MonitorHandle
-//! [loop_get]: ../event_loop/struct.EventLoop.html#method.available_monitors
+//! [loop_get]: crate::event_loop::EventLoop::available_monitors
-//! [window_get]: ../window/struct.Window.html#method.available_monitors
+//! [window_get]: crate::window::Window::available_monitors
 use crate::{
     dpi::{PhysicalPosition, PhysicalSize},
     platform_impl,
@@ -19,7 +19,7 @@ use crate::{
 /// Can be acquired with:
 /// - [`MonitorHandle::video_modes`][monitor_get].
 ///
-/// [monitor_get]: ../monitor/struct.MonitorHandle.html#method.video_modes
+/// [monitor_get]: crate::monitor::MonitorHandle::video_modes
 #[derive(Clone, PartialEq, Eq, Hash)]
 pub struct VideoMode {
     pub(crate) video_mode: platform_impl::VideoMode,
@@ -108,7 +108,7 @@ impl std::fmt::Display for VideoMode {
 ///
 /// Allows you to retrieve information about a given monitor and can be used in [`Window`] creation.
 ///
-/// [`Window`]: ../window/struct.Window.html
+/// [`Window`]: crate::window::Window
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub struct MonitorHandle {
     pub(crate) inner: platform_impl::MonitorHandle,
@@ -150,7 +150,7 @@ impl MonitorHandle {
 
     /// Returns the DPI factor that can be used to map logical pixels to physical pixels, and vice versa.
     ///
-    /// See the [`dpi`](../dpi/index.html) module for more information.
+    /// See the [`dpi`](crate::dpi) module for more information.
     ///
     /// ## Platform-specific
     ///

src/window.rs

@@ -195,7 +195,7 @@ impl WindowBuilder {
     ///
     /// See [`Window::set_inner_size`] for details.
     ///
-    /// [`Window::set_inner_size`]: struct.Window.html#method.set_inner_size
+    /// [`Window::set_inner_size`]: crate::window::Window::set_inner_size
     #[inline]
     pub fn with_inner_size(mut self, size: LogicalSize) -> Self {
         self.window.inner_size = Some(size);
@@ -206,7 +206,7 @@ impl WindowBuilder {
     ///
     /// See [`Window::set_min_inner_size`] for details.
     ///
-    /// [`Window::set_min_inner_size`]: struct.Window.html#method.set_min_inner_size
+    /// [`Window::set_min_inner_size`]: crate::window::Window::set_min_inner_size
     #[inline]
     pub fn with_min_inner_size(mut self, min_size: LogicalSize) -> Self {
         self.window.min_inner_size = Some(min_size);
@@ -217,7 +217,7 @@ impl WindowBuilder {
     ///
     /// See [`Window::set_max_inner_size`] for details.
     ///
-    /// [`Window::set_max_inner_size`]: struct.Window.html#method.set_max_inner_size
+    /// [`Window::set_max_inner_size`]: crate::window::Window::set_max_inner_size
     #[inline]
     pub fn with_max_inner_size(mut self, max_size: LogicalSize) -> Self {
         self.window.max_inner_size = Some(max_size);
@@ -228,7 +228,7 @@ impl WindowBuilder {
     ///
     /// See [`Window::set_resizable`] for details.
     ///
-    /// [`Window::set_resizable`]: struct.Window.html#method.set_resizable
+    /// [`Window::set_resizable`]: crate::window::Window::set_resizable
     #[inline]
     pub fn with_resizable(mut self, resizable: bool) -> Self {
         self.window.resizable = resizable;
@@ -239,7 +239,7 @@ impl WindowBuilder {
     ///
     /// See [`Window::set_title`] for details.
     ///
-    /// [`Window::set_title`]: struct.Window.html#method.set_title
+    /// [`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,7 +250,7 @@ impl WindowBuilder {
     ///
     /// See [`Window::set_fullscreen`] for details.
     ///
-    /// [`Window::set_fullscreen`]: struct.Window.html#method.set_fullscreen
+    /// [`Window::set_fullscreen`]: crate::window::Window::set_fullscreen
     #[inline]
     pub fn with_fullscreen(mut self, monitor: Option<Fullscreen>) -> Self {
         self.window.fullscreen = monitor;
@@ -261,7 +261,7 @@ impl WindowBuilder {
     ///
     /// See [`Window::set_maximized`] for details.
     ///
-    /// [`Window::set_maximized`]: struct.Window.html#method.set_maximized
+    /// [`Window::set_maximized`]: crate::window::Window::set_maximized
     #[inline]
     pub fn with_maximized(mut self, maximized: bool) -> Self {
         self.window.maximized = maximized;
@@ -272,7 +272,7 @@ impl WindowBuilder {
     ///
     /// See [`Window::set_visible`] for details.
     ///
-    /// [`Window::set_visible`]: struct.Window.html#method.set_visible
+    /// [`Window::set_visible`]: crate::window::Window::set_visible
     #[inline]
     pub fn with_visible(mut self, visible: bool) -> Self {
         self.window.visible = visible;
@@ -290,7 +290,7 @@ impl WindowBuilder {
     ///
     /// See [`Window::set_decorations`] for details.
     ///
-    /// [`Window::set_decorations`]: struct.Window.html#method.set_decorations
+    /// [`Window::set_decorations`]: crate::window::Window::set_decorations
     #[inline]
     pub fn with_decorations(mut self, decorations: bool) -> Self {
         self.window.decorations = decorations;
@@ -301,7 +301,7 @@ impl WindowBuilder {
     ///
     /// See [`Window::set_always_on_top`] for details.
     ///
-    /// [`Window::set_always_on_top`]: struct.Window.html#method.set_always_on_top
+    /// [`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;
@@ -312,7 +312,7 @@ impl WindowBuilder {
     ///
     /// See [`Window::set_window_icon`] for details.
     ///
-    /// [`Window::set_window_icon`]: struct.Window.html#method.set_window_icon
+    /// [`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;
@@ -353,7 +353,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)`]: struct.WindowBuilder.html#method.build
+    /// [`WindowBuilder::new().build(event_loop)`]: crate::window::WindowBuilder::build
     #[inline]
     pub fn new<T: 'static>(event_loop: &EventLoopWindowTarget<T>) -> Result<Window, OsError> {
         let builder = WindowBuilder::new();
@@ -368,7 +368,7 @@ impl Window {
 
     /// Returns the DPI factor that can be used to map logical pixels to physical pixels, and vice versa.
     ///
-    /// See the [`dpi`](../dpi/index.html) module for more information.
+    /// 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::HiDpiFactorChanged` events is
@@ -595,16 +595,13 @@ impl Window {
     ///
     ///   `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`][simple] if
+    ///   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.
     /// - **iOS:** Can only be called on the main thread.
     /// - **Wayland:** Does not support exclusive fullscreen mode.
     /// - **Windows:** Screen saver is disabled in fullscreen mode.
-    ///
-    /// [simple]:
-    /// ../platform/macos/trait.WindowExtMacOS.html#tymethod.set_simple_fullscreen
     #[inline]
     pub fn set_fullscreen(&self, fullscreen: Option<Fullscreen>) {
         self.window.set_fullscreen(fullscreen)