Explain Window metrics better. (flutter#4555)

lib/ui/window.dart

@@ -328,6 +328,8 @@ class Window {
   /// The Flutter framework operates in logical pixels, so it is rarely
   /// necessary to directly deal with this property.
   ///
+  /// When this changes, [onMetricsChanged] is called.
+  ///
   /// See also:
   ///
   ///  * [WidgetsBindingObserver], for a mechanism at the widgets layer to
@@ -338,6 +340,16 @@ class Window {
   /// The dimensions of the rectangle into which the application will be drawn,
   /// in physical pixels.
   ///
+  /// When this changes, [onMetricsChanged] is called.
+  ///
+  /// At startup, the size of the application window may not be know before Dart
+  /// code runs. If this value is observed early in the application lifecycle,
+  /// it may report [Size.zero].
+  ///
+  /// This value does not take into account any on-screen keyboards or other
+  /// system UI. The [padding] and [viewInsets] properties provide a view into
+  /// how much of each side of the application may be obscured by system UI.
+  ///
   /// See also:
   ///
   ///  * [WidgetsBindingObserver], for a mechanism at the widgets layer to
@@ -350,6 +362,8 @@ class Window {
   /// will likely place system UI, such as the keyboard, that fully obscures
   /// any content.
   ///
+  /// When this changes, [onMetricsChanged] is called.
+  ///
   /// See also:
   ///
   ///  * [WidgetsBindingObserver], for a mechanism at the widgets layer to
@@ -366,6 +380,8 @@ class Window {
   /// intrusions in the display (e.g. overscan regions on television screens or
   /// phone sensor housings).
   ///
+  /// When this changes, [onMetricsChanged] is called.
+  ///
   /// See also:
   ///
   ///  * [WidgetsBindingObserver], for a mechanism at the widgets layer to
@@ -381,8 +397,17 @@ class Window {
   /// when the device is rotated or when the application is resized (e.g. when
   /// showing applications side-by-side on Android).
   ///
-  /// The framework invokes this callback in the same zone in which the
-  /// callback was set.
+  /// The engine invokes this callback in the same zone in which the callback
+  /// was set.
+  ///
+  /// The framework registers with this callback and updates the layout
+  /// appropriately.
+  ///
+  /// See also:
+  ///
+  ///  * [WidgetsBindingObserver], for a mechanism at the widgets layer to
+  ///    register for notifications when this is called.
+  ///  * [MediaQuery.of], a simpler mechanism for the same.
   VoidCallback get onMetricsChanged => _onMetricsChanged;
   VoidCallback _onMetricsChanged;
   Zone _onMetricsChangedZone;