winit-core: drop broken docs

Generally, winit-core doesn't know about underlying platforms, though,
some general information which will true for any implementation was
left in place.

src/event_loop.rs

@@ -132,6 +132,8 @@ impl EventLoop {
 
     /// Run the application with the event loop on the calling thread.
     ///
+    /// The `app` is dropped when the event loop is shut down.
+    ///
     /// ## Event loop flow
     ///
     /// This function internally handles the different parts of a traditional event-handling loop.

src/platform/ios.rs

@@ -284,6 +284,7 @@ impl WindowExtIOS for dyn Window + '_ {
     }
 }
 
+/// Ios specific window attributes.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct WindowAttributesIos {
     pub(crate) scale_factor: Option<f64>,
@@ -294,7 +295,6 @@ pub struct WindowAttributesIos {
     pub(crate) preferred_screen_edges_deferring_system_gestures: ScreenEdge,
 }
 
-/// Additional methods on [`WindowAttributes`] that are specific to iOS.
 impl WindowAttributesIos {
     /// Sets the [`contentScaleFactor`] of the underlying [`UIWindow`] to `scale_factor`.
     ///

src/platform/macos.rs

@@ -294,7 +294,7 @@ pub enum ActivationPolicy {
     Prohibited,
 }
 
-/// [`WindowAttributes`] that are specific to MacOS.
+/// Window attributes that are specific to MacOS.
 ///
 /// **Note:** Properties dealing with the titlebar will be overwritten by the
 /// [`WindowAttributes::with_decorations`] method:
@@ -303,6 +303,8 @@ pub enum ActivationPolicy {
 /// - `with_titlebar_hidden`
 /// - `with_titlebar_buttons_hidden`
 /// - `with_fullsize_content_view`
+///
+/// [`WindowAttributes::with_decorations`]: crate::window::WindowAttributes::with_decorations
 #[derive(Clone, Debug, PartialEq)]
 pub struct WindowAttributesMacOS {
     pub(crate) movable_by_window_background: bool,

src/platform/web.rs

@@ -13,9 +13,9 @@
 //! yourself.
 //!
 //! [canvas]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement
-//! [with_canvas]: WindowAttributesExtWeb::with_canvas
+//! [with_canvas]: WindowAttributesWeb::with_canvas
 //! [get]: WindowExtWeb::canvas
-//! [insert]: WindowAttributesExtWeb::with_append
+//! [insert]: WindowAttributesWeb::with_append
 #![cfg_attr(not(web_platform), doc = "[wasm_bindgen]: https://docs.rs/wasm-bindgen")]
 //! [Rust and WebAssembly book]: https://rustwasm.github.io/book
 //!
@@ -139,7 +139,7 @@ pub struct WindowAttributesWeb {
 
 impl WindowAttributesWeb {
     /// Pass an [`HtmlCanvasElement`] to be used for this [`Window`]. If [`None`],
-    /// [`WindowAttributes::default()`] will create one.
+    /// the default one will be created.
     ///
     /// In any case, the canvas won't be automatically inserted into the Web page.
     ///

src/platform/windows.rs

@@ -242,7 +242,7 @@ pub trait WindowExtWindows {
     ///
     /// A window must be enabled before it can be activated.
     /// If an application has create a modal dialog box by disabling its owner window
-    /// (as described in [`WindowAttributesExtWindows::with_owner_window`]), the application must
+    /// (as described in [`WindowAttributesWindows::with_owner_window`]), the application must
     /// enable the owner window before destroying the dialog box.
     /// Otherwise, another window will receive the keyboard focus and be activated.
     ///
@@ -502,6 +502,8 @@ impl WindowAttributesWindows {
     /// - An owned window is hidden when its owner is minimized.
     ///
     /// For more information, see <https://docs.microsoft.com/en-us/windows/win32/winmsg/window-features#owned-windows>
+    ///
+    /// [`WindowAttributes::with_parent_window`]: crate::window::WindowAttributes::with_parent_window
     pub fn with_owner_window(mut self, parent: HWND) -> Self {
         self.owner = Some(parent);
         self
@@ -516,6 +518,8 @@ impl WindowAttributesWindows {
     /// 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.
+    #[rustfmt::skip]
+    ///
     #[cfg_attr(
         windows_platform,
         doc = "[`CreateMenu`]: windows_sys::Win32::UI::WindowsAndMessaging::CreateMenu"

winit-core/Cargo.toml

@@ -28,3 +28,6 @@ web-time = "1"
 
 [build-dependencies]
 cfg_aliases = "0.2.1"
+
+[dev-dependencies]
+winit = { path = ".." }

winit-core/src/event.rs

@@ -618,17 +618,8 @@ pub enum DeviceEvent {
     /// ## Platform-specific
     ///
     /// **Web:** Only returns raw data, not OS accelerated, if [`CursorGrabMode::Locked`] is used
-    /// and browser support is available, see
+    /// and browser support is available.
-    #[cfg_attr(
-        web_platform,
-        doc = "[`ActiveEventLoopExtWeb::is_cursor_lock_raw()`][crate::platform::web::ActiveEventLoopExtWeb::is_cursor_lock_raw()]."
-    )]
-    #[cfg_attr(
-        not(web_platform),
-        doc = "`ActiveEventLoopExtWeb::is_cursor_lock_raw()`."
-    )]
     ///
-    #[rustfmt::skip]
     /// [`CursorGrabMode::Locked`]: crate::window::CursorGrabMode::Locked
     PointerMotion {
         /// (x, y) change in position in unspecified units.

winit-core/src/event_loop.rs

@@ -46,12 +46,7 @@ pub trait ActiveEventLoop: AsAny + fmt::Debug {
     ///
     /// ## Platform-specific
     ///
-    /// **Web:** Only returns the current monitor without
+    /// **Web:** Only returns the current monitor without `detailed monitor permissions`.
-    #[cfg_attr(
-        web_platform,
-        doc = "[detailed monitor permissions][crate::platform::web::ActiveEventLoopExtWeb::request_detailed_monitor_permission]."
-    )]
-    #[cfg_attr(not(web_platform), doc = "detailed monitor permissions.")]
     fn available_monitors(&self) -> Box<dyn Iterator<Item = MonitorHandle>>;
 
     /// Returns the primary monitor of the system.
@@ -61,12 +56,7 @@ pub trait ActiveEventLoop: AsAny + fmt::Debug {
     /// ## Platform-specific
     ///
     /// - **Wayland:** Always returns `None`.
-    /// - **Web:** Always returns `None` without
+    /// - **Web:** Always returns `None` without `detailed monitor permissions`.
-    #[cfg_attr(
-        web_platform,
-        doc = "  [detailed monitor permissions][crate::platform::web::ActiveEventLoopExtWeb::request_detailed_monitor_permission]."
-    )]
-    #[cfg_attr(not(web_platform), doc = "  detailed monitor permissions.")]
     fn primary_monitor(&self) -> Option<MonitorHandle>;
 
     /// Change if or when [`DeviceEvent`]s are captured.

winit-core/src/monitor.rs

@@ -29,20 +29,9 @@ use crate::as_any::{impl_dyn_casting, AsAny};
 ///
 /// ## Platform-specific
 ///
-/// **Web:** A [`MonitorHandle`] created without
+/// **Web:** A [`MonitorHandle`] created without `detailed monitor permissions`
-#[cfg_attr(
-    web_platform,
-    doc = "[detailed monitor permissions][crate::platform::web::ActiveEventLoopExtWeb::request_detailed_monitor_permission]."
-)]
-#[cfg_attr(not(web_platform), doc = "detailed monitor permissions.")]
 /// will always represent the current monitor the browser window is in instead of a specific
-/// monitor. See
+/// monitor.
-#[cfg_attr(
-    web_platform,
-    doc = "[`MonitorHandleExtWeb::is_detailed()`][crate::platform::web::MonitorHandleExtWeb::is_detailed]"
-)]
-#[cfg_attr(not(web_platform), doc = "`MonitorHandleExtWeb::is_detailed()`")]
-/// to check.
 ///
 /// [`Window`]: crate::window::Window
 #[derive(Debug, Clone)]
@@ -88,14 +77,10 @@ pub trait MonitorHandleProvider: AsAny + fmt::Debug + Send + Sync {
     ///
     /// Returns `None` if the monitor doesn't exist anymore or the name couldn't be obtained.
     ///
+    ///
     /// ## Platform-specific
     ///
-    /// **Web:** Always returns [`None`] without
+    /// **Web:** Always returns [`None`] without `detailed monitor permissions`.
-    #[cfg_attr(
-        web_platform,
-        doc = "[detailed monitor permissions][crate::platform::web::ActiveEventLoopExtWeb::request_detailed_monitor_permission]."
-    )]
-    #[cfg_attr(not(web_platform), doc = "detailed monitor permissions.")]
     fn name(&self) -> Option<Cow<'_, str>>;
 
     /// Returns the top-left corner position of the monitor in desktop coordinates.
@@ -106,12 +91,7 @@ pub trait MonitorHandleProvider: AsAny + fmt::Debug + Send + Sync {
     ///
     /// ## Platform-specific
     ///
-    /// **Web:** Always returns [`None`] without
+    /// **Web:** Always returns [`None`] without `detailed monitor permissions`.
-    #[cfg_attr(
-        web_platform,
-        doc = "[detailed monitor permissions][crate::platform::web::ActiveEventLoopExtWeb::request_detailed_monitor_permission]."
-    )]
-    #[cfg_attr(not(web_platform), doc = "detailed monitor permissions.")]
     fn position(&self) -> Option<PhysicalPosition<i32>>;
 
     /// Returns the scale factor of the underlying monitor. To map logical pixels to physical
@@ -119,19 +99,9 @@ pub trait MonitorHandleProvider: AsAny + fmt::Debug + Send + Sync {
     ///
     /// See the [`dpi`] module for more information.
     ///
-    /// ## Platform-specific
-    ///
-    /// - **X11:** Can be overridden using the `WINIT_X11_SCALE_FACTOR` environment variable.
     /// - **Wayland:** May differ from [`Window::scale_factor`].
-    /// - **Android:** Always returns 1.0.
+    /// - **Web:** Always returns `0.0` without `detailed_monitor_permissions`.
-    /// - **Web:** Always returns `0.0` without
-    #[cfg_attr(
-        web_platform,
-        doc = "  [detailed monitor permissions][crate::platform::web::ActiveEventLoopExtWeb::request_detailed_monitor_permission]."
-    )]
-    #[cfg_attr(not(web_platform), doc = "  detailed monitor permissions.")]
     ///
-    #[rustfmt::skip]
     /// [`Window::scale_factor`]: crate::window::Window::scale_factor
     fn scale_factor(&self) -> f64;
 

winit-core/src/window.rs

@@ -624,7 +624,7 @@ pub trait Window: AsAny + Send + Sync + fmt::Debug {
     ///
     /// This may also be useful for figuring out the size of the window's decorations (such as
     /// buttons, title, etc.), but may also not correspond to that (e.g. if the title bar is made
-    /// transparent using [`with_titlebar_transparent`] on macOS, or your are drawing window
+    /// transparent on macOS, or your are drawing window
     /// decorations yourself).
     ///
     /// This may be negative.
@@ -633,15 +633,6 @@ pub trait Window: AsAny + Send + Sync + fmt::Debug {
     /// as the window itself, this simply returns `(0, 0)`.
     ///
     /// [`outer_position`]: Self::outer_position
-    #[cfg_attr(
-        macos_platform,
-        doc = "[`with_titlebar_transparent`]: \
-               crate::platform::macos::WindowAttributesExtMacOS::with_titlebar_transparent"
-    )]
-    #[cfg_attr(
-        not(macos_platform),
-        doc = "[`with_titlebar_transparent`]: #only-available-on-macos"
-    )]
     fn surface_position(&self) -> PhysicalPosition<i32>;
 
     /// The position of the top-left hand corner of the window relative to the top-left hand corner
@@ -1004,14 +995,8 @@ pub trait Window: AsAny + Send + Sync + fmt::Debug {
     ///   The dock and the menu bar are disabled in exclusive fullscreen mode.
     /// - **Wayland:** Does not support exclusive fullscreen mode and will no-op a request.
     /// - **Windows:** Screen saver is disabled in fullscreen mode.
-    /// - **Android / Orbital:** Unsupported.
+    /// - **Web:** Passing a [`MonitorHandle`] or [`VideoMode`] that was not created with detailed
-    /// - **Web:** Passing a [`MonitorHandle`] or [`VideoMode`] that was not created with
+    ///   monitor permissions or calling without a [transient activation] does nothing.
-    #[cfg_attr(
-        web_platform,
-        doc = "  [detailed monitor permissions][crate::platform::web::ActiveEventLoopExtWeb::request_detailed_monitor_permission]"
-    )]
-    #[cfg_attr(not(web_platform), doc = "  detailed monitor permissions")]
-    ///   or calling without a [transient activation] does nothing.
     ///
     /// [transient activation]: https://developer.mozilla.org/en-US/docs/Glossary/Transient_activation
     /// [`VideoMode`]: crate::monitor::VideoMode
@@ -1333,17 +1318,6 @@ pub trait Window: AsAny + Send + Sync + fmt::Debug {
     /// This is the same as [`ActiveEventLoop::available_monitors`], and is provided for
     /// convenience.
     ///
-    ///
-    /// ## Platform-specific
-    ///
-    /// **Web:** Only returns the current monitor without
-    #[cfg_attr(
-        web_platform,
-        doc = "[detailed monitor permissions][crate::platform::web::ActiveEventLoopExtWeb::request_detailed_monitor_permission]."
-    )]
-    #[cfg_attr(not(any(web_platform,)), doc = "detailed monitor permissions.")]
-    ///
-    #[rustfmt::skip]
     /// [`ActiveEventLoop::available_monitors`]: crate::event_loop::ActiveEventLoop::available_monitors
     fn available_monitors(&self) -> Box<dyn Iterator<Item = MonitorHandle>>;
 
@@ -1356,14 +1330,7 @@ pub trait Window: AsAny + Send + Sync + fmt::Debug {
     /// ## Platform-specific
     ///
     /// - **Wayland:** Always returns `None`.
-    /// - **Web:** Always returns `None` without
-    #[cfg_attr(
-        web_platform,
-        doc = "  [detailed monitor permissions][crate::platform::web::ActiveEventLoopExtWeb::request_detailed_monitor_permission]."
-    )]
-    #[cfg_attr(not(web_platform), doc = "  detailed monitor permissions.")]
     ///
-    #[rustfmt::skip]
     /// [`ActiveEventLoop::primary_monitor`]: crate::event_loop::ActiveEventLoop::primary_monitor
     fn primary_monitor(&self) -> Option<MonitorHandle>;