Clarify scale_factor docs

Wayland scales each window individually, thus make it clear. Also
recommend against using the `MonitorHandle::scale_factor`.

Fixes #3183.

src/dpi.rs

@@ -82,7 +82,8 @@
 //!   If `WINIT_X11_SCALE_FACTOR` is set to `randr`, it'll ignore the `Xft.dpi` field and use the
 //!   XRandR scaling method. Generally speaking, you should try to configure the standard system
 //!   variables to do what you want before resorting to `WINIT_X11_SCALE_FACTOR`.
-//! - **Wayland:** Scale factor is suggested by the the compositor.
+//! - **Wayland:** Scale factor is suggested by the compositor for each window individually. The
+//!   monitor scale factor may differ from the window scale factor.
 //! - **iOS:** Scale factors are set by Apple to the value that best suits the device, and range
 //!   from `1.0` to `3.0`. See [this article][apple_1] and [this article][apple_2] for more
 //!   information.

src/monitor.rs

@@ -138,14 +138,18 @@ impl MonitorHandle {
         self.inner.refresh_rate_millihertz()
     }
 
-    /// Returns the scale factor that can be used to map logical pixels to physical pixels, and vice versa.
+    /// Returns the scale factor of the underlying monitor. To map logical pixels to physical
+    /// pixels and vice versa, use [`Window::scale_factor`].
     ///
     /// See the [`dpi`](crate::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.
+    ///
+    /// [`Window::scale_factor`]: crate::window::Window::scale_factor
     #[inline]
     pub fn scale_factor(&self) -> f64 {
         self.inner.scale_factor()

src/window.rs

@@ -543,14 +543,17 @@ impl Window {
         self.window.maybe_wait_on_main(|w| WindowId(w.id()))
     }
 
-    /// Returns the scale factor that can be used to map logical pixels to physical pixels, and vice versa.
+    /// Returns the scale factor that can be used to map logical pixels to physical pixels, and
-    ///
+    /// vice versa.
-    /// 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::ScaleFactorChanged`] events is
     /// the most robust way to track the DPI you need to use to draw.
     ///
+    /// This value may differ from [`MonitorHandle::scale_factor`].
+    ///
+    /// See the [`dpi`](crate::dpi) module for more information.
+    ///
     /// ## Platform-specific
     ///
     /// - **X11:** This respects Xft.dpi, and can be overridden using the `WINIT_X11_SCALE_FACTOR` environment variable.