From 08bae037f09914df5d843d8db8e26ac341726e8b Mon Sep 17 00:00:00 2001 From: Osspial Date: Mon, 11 Nov 2019 18:05:59 -0500 Subject: [PATCH] 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 + .travis.yml | 2 ++ appveyor.yml | 1 + src/dpi.rs | 18 ++++++++-------- src/event.rs | 6 +++--- src/event_loop.rs | 10 ++++----- src/lib.rs | 35 ++++++++++++++++---------------- src/monitor.rs | 16 +++++++-------- src/window.rs | 31 +++++++++++++--------------- 9 files changed, 61 insertions(+), 59 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index ecbd5d4b..1cb88dcc 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.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 diff --git a/.travis.yml b/.travis.yml index 7a73219b..649b0106 100644 --- a/.travis.yml +++ b/.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 diff --git a/appveyor.yml b/appveyor.yml index 69d35658..20ee2cc7 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -32,3 +32,4 @@ build: false test_script: - cargo test --verbose - cargo test --features serde --verbose + - cargo doc --no-deps diff --git a/src/dpi.rs b/src/dpi.rs index 99848ae9..27fbbc49 100644 --- a/src/dpi.rs +++ b/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 -//! changes, and [`HiDpiFactorChanged`](../enum.WindowEvent.html#variant.HiDpiFactorChanged) events +//! `winit` will send [`Resized`](event::WindowEvent::Resized) events whenever a window's logical size +//! 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`. diff --git a/src/event.rs b/src/event.rs index a6aa9bd0..c06f3c3d 100644 --- a/src/event.rs +++ b/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 { 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), } diff --git a/src/event_loop.rs b/src/event_loop.rs index 0935fc72..fd9e034f 100644 --- a/src/event_loop.rs +++ b/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 -//! [event_loop_proxy]: ./struct.EventLoopProxy.html -//! [send_event]: ./struct.EventLoopProxy.html#method.send_event +//! [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::ops::Deref; use std::{error, fmt}; @@ -68,7 +68,7 @@ impl fmt::Debug for EventLoopWindowTarget { /// 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 EventLoop { /// /// Any values not passed to this function will *not* be dropped. /// - /// [`ControlFlow`]: ./enum.ControlFlow.html + /// [`ControlFlow`]: crate::event_loop::ControlFlow #[inline] pub fn run(self, event_handler: F) -> ! where diff --git a/src/lib.rs b/src/lib.rs index 8d5447f7..5a3f6c9b 100644 --- a/src/lib.rs +++ b/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::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.WindowEvent.html -//! [`DeviceEvent`]: ./event/enum.DeviceEvent.html -//! [`UserEvent`]: ./event/enum.Event.html#variant.UserEvent -//! [`LoopDestroyed`]: ./event/enum.Event.html#variant.LoopDestroyed -//! [`platform`]: ./platform/index.html +//! [`EventLoop`]: event_loop::EventLoop +//! [`EventLoop::new()`]: event_loop::EventLoop::new +//! [event_loop_run]: event_loop::EventLoop::run +//! [`ControlFlow`]: event_loop::ControlFlow +//! [`Exit`]: event_loop::ControlFlow::Exit +//! [`Window`]: window::Window +//! [`WindowBuilder`]: window::WindowBuilder +//! [window_new]: window::Window::new +//! [window_builder_new]: window::WindowBuilder::new +//! [window_builder_build]: window::WindowBuilder::build +//! [window_id_fn]: window::Window::id +//! [`Event`]: event::Event +//! [`WindowEvent`]: event::WindowEvent +//! [`DeviceEvent`]: event::DeviceEvent +//! [`UserEvent`]: event::Event::UserEvent +//! [`LoopDestroyed`]: event::Event::LoopDestroyed +//! [`platform`]: platform #![deny(rust_2018_idioms)] +#![deny(intra_doc_link_resolution_failure)] #[allow(unused_imports)] #[macro_use] diff --git a/src/monitor.rs b/src/monitor.rs index 9ef58be5..417596c3 100644 --- a/src/monitor.rs +++ b/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 -//! [loop_get]: ../event_loop/struct.EventLoop.html#method.available_monitors -//! [window_get]: ../window/struct.Window.html#method.available_monitors +//! [monitor_handle]: crate::monitor::MonitorHandle +//! [loop_get]: crate::event_loop::EventLoop::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 /// diff --git a/src/window.rs b/src/window.rs index 8384cb23..fedd3d0a 100644 --- a/src/window.rs +++ b/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>(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) -> 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) -> 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(event_loop: &EventLoopWindowTarget) -> Result { 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) { self.window.set_fullscreen(fullscreen)