More documentation for MediaQuery and friends (#130509)

Fixes flutter/flutter#11697

Author: Hixie

packages/flutter/lib/src/widgets/media_query.dart

@@ -219,6 +219,10 @@ class MediaQueryData {
   /// this method again when it changes to keep the constructed [MediaQueryData]
   /// updated.
   ///
+  /// In general, [MediaQuery.of] is the appropriate way to obtain
+  /// [MediaQueryData] from a widget. This `fromView` constructor is primarily
+  /// for use in the implementation of the framework itself.
+  ///
   /// See also:
   ///
   ///  * [MediaQuery.fromView], which constructs [MediaQueryData] from a provided
@@ -262,9 +266,12 @@ class MediaQueryData {
   /// It is considered bad practice to cache and later use the size returned
   /// by `MediaQuery.of(context).size`. It will make the application non responsive
   /// and might lead to unexpected behaviors.
-  /// For instance, during startup, especially in release mode, the first returned
-  /// size might be (0,0). The size will be updated when the native platform
-  /// reports the actual resolution.
+  ///
+  /// For instance, during startup, especially in release mode, the first
+  /// returned size might be (0,0). The size will be updated when the native
+  /// platform reports the actual resolution. Using [MediaQuery.of] will ensure
+  /// that when the size changes, any widgets depending on the size are
+  /// automatically rebuilt.
   ///
   /// See the article on [Creating responsive and adaptive
   /// apps](https://docs.flutter.dev/development/ui/layout/adaptive-responsive)

packages/flutter/lib/src/widgets/view.dart

@@ -21,6 +21,15 @@ import 'media_query.dart';
 /// The provided [child] is wrapped in a [MediaQuery] constructed from the given
 /// [view].
 ///
+/// For most use cases, using [MediaQuery.of] is a more appropriate way of
+/// obtaining the information that a [FlutterView] exposes. For example, using
+/// [MediaQuery] will expose the _logical_ device size ([MediaQueryData.size])
+/// rather than the physical size ([FlutterView.physicalSize]). Similarly, while
+/// [FlutterView.padding] conveys the information from the operating system, the
+/// [MediaQueryData.padding] further adjusts this information to be aware of the
+/// context of the widget; e.g. the [Scaffold] widget adjusts the values for its
+/// various children.
+///
 /// Each [FlutterView] can be associated with at most one [View] widget in the
 /// widget tree. Two or more [View] widgets configured with the same
 /// [FlutterView] must never exist within the same widget tree at the same time.
@@ -93,7 +102,7 @@ class View extends StatelessWidget {
   /// The method creates a dependency on the `context`, which will be informed
   /// when the identity of the [FlutterView] changes (i.e. the `context` is
   /// moved to render into a different [FlutterView] then before). The context
-  /// will not be informed when the properties on the [FlutterView] itself
+  /// will not be informed when the _properties_ on the [FlutterView] itself
   /// change their values. To access the property values of a [FlutterView] it
   /// is best practise to use [MediaQuery.maybeOf] instead, which will ensure
   /// that the `context` is informed when the view properties change.
@@ -113,7 +122,7 @@ class View extends StatelessWidget {
   /// The method creates a dependency on the `context`, which will be informed
   /// when the identity of the [FlutterView] changes (i.e. the `context` is
   /// moved to render into a different [FlutterView] then before). The context
-  /// will not be informed when the properties on the [FlutterView] itself
+  /// will not be informed when the _properties_ on the [FlutterView] itself
   /// change their values. To access the property values of a [FlutterView] it
   /// is best practise to use [MediaQuery.of] instead, which will ensure that
   /// the `context` is informed when the view properties change.