Clarify DPI docs to highlight WindowEvent::HiDpiFactorChanged (#598)

* Clarify DPI docs to highlight WindowEvent::HiDpiFactorChanged

* Address review of #598

* dpi docs: grammar corrections

* The final nitpick

src/dpi.rs

@@ -28,10 +28,20 @@
 //! feel like they have bad eyesight, which will potentially cause them to think about growing elderly, resulting in
 //! them entering an existential panic. Once users enter that state, they will no longer be focused on your application.
 //!
-//! There are two ways to get the DPI factor: either by calling
-//! [`MonitorId::get_hidpi_factor`](../struct.MonitorId.html#method.get_hidpi_factor), or
-//! [`Window::get_hidpi_factor`](../struct.Window.html#method.get_hidpi_factor). You'll almost always use the latter,
-//! which is basically equivalent to `window.get_current_monitor().get_hidpi_factor()` anyway.
+//! There are two ways to get the DPI factor:
+//! - You can track the `WindowEvent::HiDpiFactorChanged` event of your windows. This event is sent any
+//!   time the DPI factor changes, be it because the window moved to another monitor, or because the
+//!   user changed the configuration of their screen.
+//! - You can also retrieve the DPI factor of a monitor by calling
+//!   [`MonitorId::get_hidpi_factor`](../struct.MonitorId.html#method.get_hidpi_factor), or the
+//!   current DPI factor applied to a window by calling
+//!   [`Window::get_hidpi_factor`](../struct.Window.html#method.get_hidpi_factor), which is roughly equivalent
+//!   to `window.get_current_monitor().get_hidpi_factor()`.
+//!
+//! Depending on the platform, the window's actual DPI factor may only be known after
+//! the event loop has started and your window has been drawn once. To properly handle these cases,
+//! the most robust way is to monitor the `WindowEvent::HiDpiFactorChanged` event and dynamically
+//! adapt your drawing logic to follow the DPI factor.
 //!
 //! Here's an overview of what sort of DPI factors you can expect, and where they come from:
 //! - **Windows:** On Windows 8 and 10, per-monitor scaling is readily configured by users from the display settings.

src/window.rs

@@ -304,6 +304,10 @@ impl Window {
     ///
     /// See the [`dpi`](dpi/index.html) 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::HiDpiFactorChanged` events is
+    /// the most robust way to track the DPI you need to use to draw.
+    ///
     /// ## Platform-specific
     ///
     /// - **X11:** Can be overridden using the `WINIT_HIDPI_FACTOR` environment variable.