Display all platform-specific documentation on docs.rs (#3076)

.github/workflows/ci.yml

@@ -17,6 +17,17 @@ jobs:
     - name: Check Formatting
       run: cargo fmt -- --check
 
+  docsrs:
+    name: Check building on docs.rs
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: dtolnay/rust-toolchain@nightly
+    - name: Check Formatting
+      run: cargo doc --no-deps --features=rwh_04,rwh_05,rwh_06,serde,mint,android-native-activity
+      env:
+        RUSTDOCFLAGS: '--cfg=docsrs --deny=warnings'
+
   tests:
     name: Test ${{ matrix.toolchain }} ${{ matrix.platform.name }}
     runs-on: ${{ matrix.platform.os }}

CHANGELOG.md

@@ -28,6 +28,8 @@ Unreleased` header.
 - On Web, add the ability to toggle calling `Event.preventDefault()` on `Window`.
 - **Breaking:** Remove `WindowAttributes::fullscreen()` and expose as field directly.
 - **Breaking:** Rename `VideoMode` to `VideoModeHandle` to represent that it doesn't hold static data.
+- **Breaking:** No longer export `platform::x11::XNotSupported`.
+- **Breaking:** Renamed `platform::x11::XWindowType` to `platform::x11::WindowType`.
 
 # 0.29.8
 

Cargo.toml

@@ -18,6 +18,7 @@ features = [
     "rwh_05",
     "rwh_06",
     "serde",
+    "mint",
     # Enabled to get docs to compile
     "android-native-activity",
 ]

src/lib.rs

@@ -154,7 +154,11 @@
 #![deny(unsafe_op_in_unsafe_fn)]
 #![cfg_attr(feature = "cargo-clippy", deny(warnings))]
 // Doc feature labels can be tested locally by running RUSTDOCFLAGS="--cfg=docsrs" cargo +nightly doc
-#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![cfg_attr(
+    docsrs,
+    feature(doc_auto_cfg, doc_cfg_hide),
+    doc(cfg_hide(doc, docsrs))
+)]
 #![allow(clippy::missing_safety_doc)]
 
 #[cfg(feature = "rwh_06")]

src/platform/android.rs

@@ -3,7 +3,7 @@ use crate::{
     window::{Window, WindowBuilder},
 };
 
-use android_activity::{AndroidApp, ConfigurationRef, Rect};
+use self::activity::{AndroidApp, ConfigurationRef, Rect};
 
 /// Additional methods on [`EventLoop`] that are specific to Android.
 pub trait EventLoopExtAndroid {}
@@ -89,5 +89,16 @@ pub mod activity {
     // feature enabled, so we avoid inlining it so that they're forced to view
     // it on the crate's own docs.rs page.
     #[doc(no_inline)]
+    #[cfg(android_platform)]
     pub use android_activity::*;
+
+    #[cfg(not(android_platform))]
+    #[doc(hidden)]
+    pub struct Rect;
+    #[cfg(not(android_platform))]
+    #[doc(hidden)]
+    pub struct ConfigurationRef;
+    #[cfg(not(android_platform))]
+    #[doc(hidden)]
+    pub struct AndroidApp;
 }

src/platform/ios.rs

@@ -1,8 +1,5 @@
 use std::os::raw::c_void;
 
-use icrate::Foundation::MainThreadMarker;
-use objc2::rc::Id;
-
 use crate::{
     event_loop::EventLoop,
     monitor::{MonitorHandle, VideoModeHandle},
@@ -240,8 +237,8 @@ impl MonitorHandleExtIOS for MonitorHandle {
     #[inline]
     fn ui_screen(&self) -> *mut c_void {
         // SAFETY: The marker is only used to get the pointer of the screen
-        let mtm = unsafe { MainThreadMarker::new_unchecked() };
-        Id::as_ptr(self.inner.ui_screen(mtm)) as *mut c_void
+        let mtm = unsafe { icrate::Foundation::MainThreadMarker::new_unchecked() };
+        objc2::rc::Id::as_ptr(self.inner.ui_screen(mtm)) as *mut c_void
     }
 
     #[inline]

src/platform/macos.rs

@@ -1,7 +1,5 @@
 use std::os::raw::c_void;
 
-use icrate::Foundation::MainThreadMarker;
-use objc2::rc::Id;
 #[cfg(feature = "serde")]
 use serde::{Deserialize, Serialize};
 
@@ -369,8 +367,10 @@ impl MonitorHandleExtMacOS for MonitorHandle {
 
     fn ns_screen(&self) -> Option<*mut c_void> {
         // SAFETY: We only use the marker to get a pointer
-        let mtm = unsafe { MainThreadMarker::new_unchecked() };
-        self.inner.ns_screen(mtm).map(|s| Id::as_ptr(&s) as _)
+        let mtm = unsafe { icrate::Foundation::MainThreadMarker::new_unchecked() };
+        self.inner
+            .ns_screen(mtm)
+            .map(|s| objc2::rc::Id::as_ptr(&s) as _)
     }
 }
 

src/platform/mod.rs

@@ -1,46 +1,33 @@
 //! Contains traits with platform-specific methods in them.
 //!
-//! Contains the follow OS-specific modules:
-//!
-//!  - `android`
-//!  - `ios`
-//!  - `macos`
-//!  - `unix`
-//!  - `windows`
-//!  - `web`
-//!
-//! And the following platform-specific modules:
-//!
-//! - `run_on_demand` (available on `windows`, `unix`, `macos`, `android`)
-//! - `pump_events` (available on `windows`, `unix`, `macos`, `android`)
-//!
-//! However only the module corresponding to the platform you're compiling to will be available.
+//! Only the modules corresponding to the platform you're compiling to will be available.
 
-#[cfg(android_platform)]
+#[cfg(any(android_platform, docsrs))]
 pub mod android;
-#[cfg(ios_platform)]
+#[cfg(any(ios_platform, docsrs))]
 pub mod ios;
-#[cfg(macos_platform)]
+#[cfg(any(macos_platform, docsrs))]
 pub mod macos;
-#[cfg(orbital_platform)]
+#[cfg(any(orbital_platform, docsrs))]
 pub mod orbital;
-#[cfg(any(x11_platform, wayland_platform))]
+#[cfg(any(x11_platform, wayland_platform, docsrs))]
 pub mod startup_notify;
-#[cfg(wayland_platform)]
+#[cfg(any(wayland_platform, docsrs))]
 pub mod wayland;
-#[cfg(wasm_platform)]
+#[cfg(any(wasm_platform, docsrs))]
 pub mod web;
-#[cfg(windows_platform)]
+#[cfg(any(windows_platform, docsrs))]
 pub mod windows;
-#[cfg(x11_platform)]
+#[cfg(any(x11_platform, docsrs))]
 pub mod x11;
 
 #[cfg(any(
     windows_platform,
     macos_platform,
     android_platform,
     x11_platform,
-    wayland_platform
+    wayland_platform,
+    docsrs,
 ))]
 pub mod run_on_demand;
 
@@ -49,9 +36,25 @@ pub mod run_on_demand;
     macos_platform,
     android_platform,
     x11_platform,
-    wayland_platform
+    wayland_platform,
+    docsrs,
 ))]
 pub mod pump_events;
 
+#[cfg(any(
+    windows_platform,
+    macos_platform,
+    x11_platform,
+    wayland_platform,
+    docsrs
+))]
 pub mod modifier_supplement;
+
+#[cfg(any(
+    windows_platform,
+    macos_platform,
+    x11_platform,
+    wayland_platform,
+    docsrs
+))]
 pub mod scancode;

src/platform/modifier_supplement.rs

@@ -1,5 +1,4 @@
-#![cfg(any(windows_platform, macos_platform, x11_platform, wayland_platform))]
-
+use crate::event::KeyEvent;
 use crate::keyboard::Key;
 
 /// Additional methods for the `KeyEvent` which cannot be implemented on all
@@ -22,3 +21,18 @@ pub trait KeyEventExtModifierSupplement {
     /// cannot be `Dead`.
     fn key_without_modifiers(&self) -> Key;
 }
+
+impl KeyEventExtModifierSupplement for KeyEvent {
+    #[inline]
+    fn text_with_all_modifiers(&self) -> Option<&str> {
+        self.platform_specific
+            .text_with_all_modifiers
+            .as_ref()
+            .map(|s| s.as_str())
+    }
+
+    #[inline]
+    fn key_without_modifiers(&self) -> Key {
+        self.platform_specific.key_without_modifiers.clone()
+    }
+}

src/platform/scancode.rs

@@ -1,5 +1,3 @@
-#![cfg(any(windows_platform, macos_platform, x11_platform, wayland_platform))]
-
 use crate::keyboard::{KeyCode, PhysicalKey};
 
 // TODO: Describe what this value contains for each platform
@@ -29,17 +27,24 @@ pub trait PhysicalKeyExtScancode {
     fn from_scancode(scancode: u32) -> PhysicalKey;
 }
 
-impl PhysicalKeyExtScancode for KeyCode
-where
-    PhysicalKey: PhysicalKeyExtScancode,
-{
-    #[inline]
+impl PhysicalKeyExtScancode for PhysicalKey {
+    fn to_scancode(self) -> Option<u32> {
+        crate::platform_impl::physicalkey_to_scancode(self)
+    }
+
     fn from_scancode(scancode: u32) -> PhysicalKey {
-        <PhysicalKey as PhysicalKeyExtScancode>::from_scancode(scancode)
+        crate::platform_impl::scancode_to_physicalkey(scancode)
     }
+}
 
+impl PhysicalKeyExtScancode for KeyCode {
     #[inline]
     fn to_scancode(self) -> Option<u32> {
         <PhysicalKey as PhysicalKeyExtScancode>::to_scancode(PhysicalKey::Code(self))
     }
+
+    #[inline]
+    fn from_scancode(scancode: u32) -> PhysicalKey {
+        <PhysicalKey as PhysicalKeyExtScancode>::from_scancode(scancode)
+    }
 }

src/platform/wayland.rs

@@ -4,8 +4,6 @@ use crate::{
     window::{Window, WindowBuilder},
 };
 
-use crate::platform_impl::{ApplicationName, Backend};
-
 pub use crate::window::Theme;
 
 /// Additional methods on [`EventLoopWindowTarget`] that are specific to Wayland.
@@ -36,7 +34,7 @@ pub trait EventLoopBuilderExtWayland {
 impl<T> EventLoopBuilderExtWayland for EventLoopBuilder<T> {
     #[inline]
     fn with_wayland(&mut self) -> &mut Self {
-        self.platform_specific.forced_backend = Some(Backend::Wayland);
+        self.platform_specific.forced_backend = Some(crate::platform_impl::Backend::Wayland);
         self
     }
 
@@ -67,7 +65,10 @@ pub trait WindowBuilderExtWayland {
 impl WindowBuilderExtWayland for WindowBuilder {
     #[inline]
     fn with_name(mut self, general: impl Into<String>, instance: impl Into<String>) -> Self {
-        self.platform_specific.name = Some(ApplicationName::new(general.into(), instance.into()));
+        self.platform_specific.name = Some(crate::platform_impl::ApplicationName::new(
+            general.into(),
+            instance.into(),
+        ));
         self
     }
 }

src/platform/web.rs

@@ -35,8 +35,13 @@ use crate::platform_impl::PlatformCustomCursorBuilder;
 use crate::window::CustomCursor;
 use crate::window::{Window, WindowBuilder};
 
+#[cfg(wasm_platform)]
 use web_sys::HtmlCanvasElement;
 
+#[cfg(not(wasm_platform))]
+#[doc(hidden)]
+pub struct HtmlCanvasElement;
+
 pub trait WindowExtWebSys {
     /// Only returns the canvas if called from inside the window context (the
     /// main thread).
@@ -80,6 +85,11 @@ pub trait WindowBuilderExtWebSys {
     /// In any case, the canvas won't be automatically inserted into the web page.
     ///
     /// [`None`] by default.
+    #[cfg_attr(
+        not(wasm_platform),
+        doc = "",
+        doc = "[`HtmlCanvasElement`]: #only-available-on-wasm"
+    )]
     fn with_canvas(self, canvas: Option<HtmlCanvasElement>) -> Self;
 
     /// Sets whether `event.preventDefault()` should be called on events on the

src/platform/windows.rs

@@ -2,12 +2,9 @@ use std::{ffi::c_void, path::Path};
 
 use crate::{
     dpi::PhysicalSize,
-    event::{DeviceId, KeyEvent},
+    event::DeviceId,
     event_loop::EventLoopBuilder,
-    keyboard::Key,
     monitor::MonitorHandle,
-    platform::modifier_supplement::KeyEventExtModifierSupplement,
-    platform_impl::WinIcon,
     window::{BadIcon, Icon, Window, WindowBuilder},
 };
 
@@ -185,7 +182,14 @@ pub trait WindowBuilderExtWindows {
     /// Note: Dark mode cannot be supported for win32 menus, it's simply not possible to change how the menus look.
     /// If you use this, it is recommended that you combine it with `with_theme(Some(Theme::Light))` to avoid a jarring effect.
     ///
-    /// [`CreateMenu`]: windows_sys::Win32::UI::WindowsAndMessaging::CreateMenu
+    #[cfg_attr(
+        platform_windows,
+        doc = "[`CreateMenu`]: windows_sys::Win32::UI::WindowsAndMessaging::CreateMenu"
+    )]
+    #[cfg_attr(
+        not(platform_windows),
+        doc = "[`CreateMenu`]: #only-available-on-windows"
+    )]
     fn with_menu(self, menu: HMENU) -> Self;
 
     /// This sets `ICON_BIG`. A good ceiling here is 256x256.
@@ -328,27 +332,12 @@ impl IconExtWindows for Icon {
         path: P,
         size: Option<PhysicalSize<u32>>,
     ) -> Result<Self, BadIcon> {
-        let win_icon = WinIcon::from_path(path, size)?;
+        let win_icon = crate::platform_impl::WinIcon::from_path(path, size)?;
         Ok(Icon { inner: win_icon })
     }
 
     fn from_resource(ordinal: u16, size: Option<PhysicalSize<u32>>) -> Result<Self, BadIcon> {
-        let win_icon = WinIcon::from_resource(ordinal, size)?;
+        let win_icon = crate::platform_impl::WinIcon::from_resource(ordinal, size)?;
         Ok(Icon { inner: win_icon })
     }
 }
-
-impl KeyEventExtModifierSupplement for KeyEvent {
-    #[inline]
-    fn text_with_all_modifiers(&self) -> Option<&str> {
-        self.platform_specific
-            .text_with_all_modifers
-            .as_ref()
-            .map(|s| s.as_str())
-    }
-
-    #[inline]
-    fn key_without_modifiers(&self) -> Key {
-        self.platform_specific.key_without_modifiers.clone()
-    }
-}