Improve documentation and refactor some code

src/monitor.rs

@@ -98,6 +98,23 @@ impl std::fmt::Display for VideoModeHandle {
 ///
 /// Allows you to retrieve information about a given monitor and can be used in [`Window`] creation.
 ///
+/// ## Platform-specific
+///
+/// **Web:** A [`MonitorHandle`] created without
+#[cfg_attr(
+    any(web_platform, docsrs),
+    doc = "[detailed monitor permissions][crate::platform::web::ActiveEventLoopExtWeb::request_detailed_monitor_permission]."
+)]
+#[cfg_attr(not(any(web_platform, docsrs)), doc = "detailed monitor permissions.")]
+/// will always represent the current monitor the browser window is in instead of a specific
+/// monitor. See
+#[cfg_attr(
+    any(web_platform, docsrs),
+    doc = "[`MonitorHandleExtWeb::is_detailed()`][crate::platform::web::MonitorHandleExtWeb::is_detailed]"
+)]
+#[cfg_attr(not(any(web_platform, docsrs)), doc = "`MonitorHandleExtWeb::is_detailed()`")]
+/// to check.
+///
 /// [`Window`]: crate::window::Window
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub struct MonitorHandle {

src/platform/web.rs

@@ -226,19 +226,26 @@ pub trait EventLoopExtWeb {
     /// [`ControlFlow::WaitUntil`]: crate::event_loop::ControlFlow::WaitUntil
     fn wait_until_strategy(&self) -> WaitUntilStrategy;
 
-    /// Returns if the users device has multiple screens.
+    /// Returns if the users device has multiple screens. Useful to check before prompting the user
+    /// with [`EventLoopExtWeb::request_detailed_monitor_permission()`].
     ///
     /// Browsers might always return [`false`] to reduce fingerprinting.
     fn has_multiple_screens(&self) -> Result<bool, NotSupportedError>;
 
     /// Prompts the user for permission to query detailed information about available monitors. The
     /// returned [`MonitorPermissionFuture`] can be dropped without aborting the request.
     ///
+    /// Check [`EventLoopExtWeb::has_multiple_screens()`] before unnecessarily prompting the user
+    /// for such permissions.
+    ///
     /// [`MonitorHandle`]s don't automatically make use of this after permission is granted. New
     /// [`MonitorHandle`]s have to be created instead.
     fn request_detailed_monitor_permission(&self) -> MonitorPermissionFuture;
 
     /// Returns whether the user has given permission to access detailed monitor information.
+    ///
+    /// [`MonitorHandle`]s don't automatically make use of detailed monitor information after
+    /// permission is granted. New [`MonitorHandle`]s have to be created instead.
     fn has_detailed_monitor_permission(&self) -> HasMonitorPermissionFuture;
 }
 
@@ -314,22 +321,26 @@ pub trait ActiveEventLoopExtWeb {
     /// [`CursorGrabMode::Locked`]: crate::window::CursorGrabMode::Locked
     fn is_cursor_lock_raw(&self) -> bool;
 
-    /// Returns if the users device has multiple screens.
+    /// Returns if the users device has multiple screens. Useful to check before prompting the user
+    /// with [`EventLoopExtWeb::request_detailed_monitor_permission()`].
     ///
     /// Browsers might always return [`false`] to reduce fingerprinting.
     fn has_multiple_screens(&self) -> Result<bool, NotSupportedError>;
 
     /// Prompts the user for permission to query detailed information about available monitors. The
     /// returned [`MonitorPermissionFuture`] can be dropped without aborting the request.
     ///
+    /// Check [`EventLoopExtWeb::has_multiple_screens()`] before unnecessarily prompting the user
+    /// for such permissions.
+    ///
     /// [`MonitorHandle`]s don't automatically make use of this after permission is granted. New
     /// [`MonitorHandle`]s have to be created instead.
     fn request_detailed_monitor_permission(&self) -> MonitorPermissionFuture;
 
     /// Returns whether the user has given permission to access detailed monitor information.
     ///
-    /// [`MonitorHandle`]s don't automatically make use of this after permission is granted. New
-    /// [`MonitorHandle`]s have to be created instead.
+    /// [`MonitorHandle`]s don't automatically make use of detailed monitor information after
+    /// permission is granted. New [`MonitorHandle`]s have to be created instead.
     fn has_detailed_monitor_permission(&self) -> bool;
 }
 
@@ -608,7 +619,9 @@ pub trait MonitorHandleExtWeb {
     /// Will fail if a locking call is in progress.
     fn unlock(&self) -> Result<(), OrientationLockError>;
 
-    /// Returns whether this [`MonitorHandle`] was created using detailed monitor permissions.
+    /// Returns whether this [`MonitorHandle`] was created using detailed monitor permissions. If
+    /// [`false`] will always represent the current monitor the browser window is in instead of a
+    /// specific monitor.
     ///
     /// See [`ActiveEventLoop::request_detailed_monitor_permission()`].
     fn is_detailed(&self) -> bool;