From 2b414cd8252865b5d7d639e8a9000ff577c27808 Mon Sep 17 00:00:00 2001
From: Marijn Suijten <marijns95@gmail.com>
Date: Fri, 17 Jun 2022 14:19:09 +0200
Subject: [PATCH] ci: Disallow warnings in rustdoc and test private items
 (#2341)

Make sure `cargo doc` runs cleanly without any warnings in the CI - some
recently introduced but still allowing a PR to get merged.

In case someone wishes to add docs on private items, make sure those
adhere to the same standards.
---
 .github/workflows/ci.yml                       |  3 ++-
 src/platform_impl/ios/app_state.rs             | 10 +++++-----
 src/platform_impl/linux/x11/event_processor.rs |  2 +-
 src/platform_impl/macos/observer.rs            |  3 ++-
 src/platform_impl/windows/event_loop.rs        |  2 +-
 src/window.rs                                  |  2 +-
 6 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 843632ad..b02af77f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -49,6 +49,7 @@ jobs:
       OPTIONS: ${{ matrix.platform.options }}
       FEATURES: ${{ format(',{0}', matrix.platform.features ) }}
       CMD: ${{ matrix.platform.cmd }}
+      RUSTDOCFLAGS: -Dwarnings
 
     runs-on: ${{ matrix.platform.os }}
     steps:
@@ -78,7 +79,7 @@ jobs:
 
     - name: Check documentation
       shell: bash
-      run: cargo $CMD doc --no-deps --target ${{ matrix.platform.target }} $OPTIONS --features $FEATURES
+      run: cargo $CMD doc --no-deps --target ${{ matrix.platform.target }} $OPTIONS --features $FEATURES --document-private-items
 
     - name: Build
       shell: bash
diff --git a/src/platform_impl/ios/app_state.rs b/src/platform_impl/ios/app_state.rs
index ed7592bd..55ed3e98 100644
--- a/src/platform_impl/ios/app_state.rs
+++ b/src/platform_impl/ios/app_state.rs
@@ -990,20 +990,20 @@ macro_rules! os_capabilities {
 }
 
 os_capabilities! {
-    /// https://developer.apple.com/documentation/uikit/uiview/2891103-safeareainsets?language=objc
+    /// <https://developer.apple.com/documentation/uikit/uiview/2891103-safeareainsets?language=objc>
     #[allow(unused)] // error message unused
     safe_area_err_msg: "-[UIView safeAreaInsets]",
     safe_area: 11-0,
-    /// https://developer.apple.com/documentation/uikit/uiviewcontroller/2887509-setneedsupdateofhomeindicatoraut?language=objc
+    /// <https://developer.apple.com/documentation/uikit/uiviewcontroller/2887509-setneedsupdateofhomeindicatoraut?language=objc>
     home_indicator_hidden_err_msg: "-[UIViewController setNeedsUpdateOfHomeIndicatorAutoHidden]",
     home_indicator_hidden: 11-0,
-    /// https://developer.apple.com/documentation/uikit/uiviewcontroller/2887507-setneedsupdateofscreenedgesdefer?language=objc
+    /// <https://developer.apple.com/documentation/uikit/uiviewcontroller/2887507-setneedsupdateofscreenedgesdefer?language=objc>
     defer_system_gestures_err_msg: "-[UIViewController setNeedsUpdateOfScreenEdgesDeferringSystem]",
     defer_system_gestures: 11-0,
-    /// https://developer.apple.com/documentation/uikit/uiscreen/2806814-maximumframespersecond?language=objc
+    /// <https://developer.apple.com/documentation/uikit/uiscreen/2806814-maximumframespersecond?language=objc>
     maximum_frames_per_second_err_msg: "-[UIScreen maximumFramesPerSecond]",
     maximum_frames_per_second: 10-3,
-    /// https://developer.apple.com/documentation/uikit/uitouch/1618110-force?language=objc
+    /// <https://developer.apple.com/documentation/uikit/uitouch/1618110-force?language=objc>
     #[allow(unused)] // error message unused
     force_touch_err_msg: "-[UITouch force]",
     force_touch: 9-0,
diff --git a/src/platform_impl/linux/x11/event_processor.rs b/src/platform_impl/linux/x11/event_processor.rs
index 1a024ac4..dea0ec85 100644
--- a/src/platform_impl/linux/x11/event_processor.rs
+++ b/src/platform_impl/linux/x11/event_processor.rs
@@ -22,7 +22,7 @@ use crate::{
     event_loop::EventLoopWindowTarget as RootELW,
 };
 
-/// The X11 documentation states: "Keycodes lie in the inclusive range [8,255]".
+/// The X11 documentation states: "Keycodes lie in the inclusive range `[8, 255]`".
 const KEYCODE_OFFSET: u8 = 8;
 
 pub(super) struct EventProcessor<T: 'static> {
diff --git a/src/platform_impl/macos/observer.rs b/src/platform_impl/macos/observer.rs
index 308637cb..2ced84ef 100644
--- a/src/platform_impl/macos/observer.rs
+++ b/src/platform_impl/macos/observer.rs
@@ -99,7 +99,8 @@ pub type CFRunLoopTimerCallBack = extern "C" fn(timer: CFRunLoopTimerRef, info:
 pub enum CFRunLoopTimerContext {}
 
 /// This mirrors the struct with the same name from Core Foundation.
-/// https://developer.apple.com/documentation/corefoundation/cfrunloopobservercontext?language=objc
+///
+/// <https://developer.apple.com/documentation/corefoundation/cfrunloopobservercontext?language=objc>
 #[allow(non_snake_case)]
 #[repr(C)]
 pub struct CFRunLoopObserverContext {
diff --git a/src/platform_impl/windows/event_loop.rs b/src/platform_impl/windows/event_loop.rs
index ff6ad5f7..7e4b7fbd 100644
--- a/src/platform_impl/windows/event_loop.rs
+++ b/src/platform_impl/windows/event_loop.rs
@@ -333,7 +333,7 @@ impl<T> EventLoopWindowTarget<T> {
 /// entrypoint.
 ///
 /// Full details of CRT initialization can be found here:
-/// https://docs.microsoft.com/en-us/cpp/c-runtime-library/crt-initialization?view=msvc-160
+/// <https://docs.microsoft.com/en-us/cpp/c-runtime-library/crt-initialization?view=msvc-160>
 fn main_thread_id() -> u32 {
     static mut MAIN_THREAD_ID: u32 = 0;
 
diff --git a/src/window.rs b/src/window.rs
index 666ebe36..ea997d6b 100644
--- a/src/window.rs
+++ b/src/window.rs
@@ -912,7 +912,7 @@ impl Window {
     ///
     /// First try confining the cursor, and if that fails, try locking it instead.
     ///
-    /// ```no-run
+    /// ```no_run
     /// # use winit::event_loop::EventLoop;
     /// # use winit::window::{CursorGrabMode, Window};
     /// # let mut event_loop = EventLoop::new();