Update `MediaQuery` documentation to highlight asynchronous nature of size (#135719)

## Description

This updates the documentation for `MediaQuery` and `Overlay` to include the following:

- That `MediaQueryData.size` is set asynchronously, and doesn't necessarily reflect the size of the current frame.
- That the specific `MediaQuery.sizeOf` and related methods are preferred over the more generic `MediaQuery.of`.
- That the size of the `Overlay` isn't necessarily the size returned by `MediaQueryData.size`

As well as adding some symbol links, and fixing some error in documentation.

## Tests
 - Documentation only

packages/flutter/lib/src/cupertino/colors.dart

@@ -984,9 +984,9 @@ class CupertinoDynamicColor extends Color with Diagnosticable {
 
   /// Resolves this [CupertinoDynamicColor] using the provided [BuildContext].
   ///
-  /// Calling this method will create a new [CupertinoDynamicColor] that is almost
-  /// identical to this [CupertinoDynamicColor], except the effective color is
-  /// changed to adapt to the given [BuildContext].
+  /// Calling this method will create a new [CupertinoDynamicColor] that is
+  /// almost identical to this [CupertinoDynamicColor], except the effective
+  /// color is changed to adapt to the given [BuildContext].
   ///
   /// For example, if the given [BuildContext] indicates the widgets in the
   /// subtree should be displayed in dark mode (the surrounding
@@ -1000,17 +1000,18 @@ class CupertinoDynamicColor extends Color with Diagnosticable {
   /// except its effective color will be the `darkHighContrastElevatedColor`
   /// variant from the original [CupertinoDynamicColor].
   ///
-  /// Calling this function may create dependencies on the closest instance of some
-  /// [InheritedWidget]s that enclose the given [BuildContext]. E.g., if [darkColor]
-  /// is different from [color], this method will call [CupertinoTheme.of], and
-  /// then [MediaQuery.of] if brightness wasn't specified in the theme data retrieved
-  /// from the previous [CupertinoTheme.of] call, in an effort to determine the
-  /// brightness value.
-  ///
-  /// If any of the required dependencies are missing from the given context, the
-  /// default value of that trait will be used ([Brightness.light] platform
-  /// brightness, normal contrast, [CupertinoUserInterfaceLevelData.base] elevation
-  /// level).
+  /// Calling this function may create dependencies on the closest instance of
+  /// some [InheritedWidget]s that enclose the given [BuildContext]. E.g., if
+  /// [darkColor] is different from [color], this method will call
+  /// [CupertinoTheme.maybeBrightnessOf] in an effort to determine the
+  /// brightness. If [color] is different from [highContrastColor], this method
+  /// will call [MediaQuery.maybeHighContrastOf] in an effort to determine the
+  /// high contrast setting.
+  ///
+  /// If any of the required dependencies are missing from the given context,
+  /// the default value of that trait will be used ([Brightness.light] platform
+  /// brightness, normal contrast, [CupertinoUserInterfaceLevelData.base]
+  /// elevation level).
   CupertinoDynamicColor resolveFrom(BuildContext context) {
     Brightness brightness = Brightness.light;
     if (_isPlatformBrightnessDependent) {

packages/flutter/lib/src/material/bottom_navigation_bar.dart

@@ -426,7 +426,7 @@ class BottomNavigationBar extends StatefulWidget {
   ///    bottom navigation bar defaults for an entire application.
   ///  * [BottomNavigationBarTheme] - which can be used to specify
   ///    bottom navigation bar defaults for a widget subtree.
-  ///  * [MediaQuery.of] - which can be used to determine the current
+  ///  * [MediaQuery.orientationOf] - which can be used to determine the current
   ///    orientation.
   final BottomNavigationBarLandscapeLayout? landscapeLayout;
 

packages/flutter/lib/src/painting/edge_insets.dart

@@ -400,7 +400,7 @@ class EdgeInsets extends EdgeInsetsGeometry {
   /// Creates insets that match the given view padding.
   ///
   /// If you need the current system padding or view insets in the context of a
-  /// widget, consider using [MediaQuery.of] to obtain these values rather than
+  /// widget, consider using [MediaQuery.paddingOf] to obtain these values rather than
   /// using the value from a [FlutterView] directly, so that you get notified of
   /// changes.
   EdgeInsets.fromViewPadding(ui.ViewPadding padding, double devicePixelRatio)

packages/flutter/lib/src/rendering/binding.dart

@@ -385,7 +385,7 @@ mixin RendererBinding on BindingBase, ServicesBinding, SchedulerBinding, Gesture
   /// changes.
   ///
   /// {@tool snippet}
-  /// Querying [MediaQuery] directly. Preferred.
+  /// Querying [MediaQuery.platformBrightnessOf] directly. Preferred.
   ///
   /// ```dart
   /// final Brightness brightness = MediaQuery.platformBrightnessOf(context);
@@ -400,15 +400,6 @@ mixin RendererBinding on BindingBase, ServicesBinding, SchedulerBinding, Gesture
   /// ```
   /// {@end-tool}
   ///
-  /// {@tool snippet}
-  /// Querying [MediaQueryData].
-  ///
-  /// ```dart
-  /// final MediaQueryData mediaQueryData = MediaQuery.of(context);
-  /// final Brightness brightness = mediaQueryData.platformBrightness;
-  /// ```
-  /// {@end-tool}
-  ///
   /// See [dart:ui.PlatformDispatcher.onPlatformBrightnessChanged].
   @protected
   void handlePlatformBrightnessChanged() { }

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

@@ -176,7 +176,7 @@ abstract mixin class WidgetsBindingObserver {
   ///
   /// See also:
   ///
-  ///  * [MediaQuery.of], which provides a similar service with less
+  ///  * [MediaQuery.sizeOf], which provides a similar service with less
   ///    boilerplate.
   void didChangeMetrics() { }
 
@@ -229,7 +229,7 @@ abstract mixin class WidgetsBindingObserver {
   ///
   /// See also:
   ///
-  ///  * [MediaQuery.of], which provides a similar service with less
+  ///  * [MediaQuery.textScaleFactorOf], which provides a similar service with less
   ///    boilerplate.
   void didChangeTextScaleFactor() { }
 
@@ -237,6 +237,11 @@ abstract mixin class WidgetsBindingObserver {
   ///
   /// This method exposes notifications from
   /// [dart:ui.PlatformDispatcher.onPlatformBrightnessChanged].
+  ///
+  /// See also:
+  ///
+  /// * [MediaQuery.platformBrightnessOf], which provides a similar service with
+  ///   less boilerplate.
   void didChangePlatformBrightness() { }
 
   /// Called when the system tells the app that the user's locale has
@@ -589,7 +594,7 @@ mixin WidgetsBinding on BindingBase, ServicesBinding, SchedulerBinding, GestureB
   /// For example, the [WidgetsApp] widget registers as a binding
   /// observer and passes the screen size to a [MediaQuery] widget
   /// each time it is built, which enables other widgets to use the
-  /// [MediaQuery.of] static method and (implicitly) the
+  /// [MediaQuery.sizeOf] static method and (implicitly) the
   /// [InheritedWidget] mechanism to be notified whenever the screen
   /// size changes (e.g. whenever the screen rotates).
   ///

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

@@ -384,6 +384,10 @@ class _OverlayEntryWidgetState extends State<_OverlayEntryWidget> {
 /// that it can resolve direction-sensitive coordinates of any
 /// [Positioned.directional] children.
 ///
+/// For widgets drawn in an [OverlayEntry], do not assume that the size of the
+/// [Overlay] is the size returned by [MediaQuery.sizeOf]. Nested overlays can
+/// have different sizes.
+///
 /// {@tool dartpad}
 /// This example shows how to use the [Overlay] to highlight the [NavigationBar]
 /// destination.

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

@@ -21,14 +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.
+/// For most use cases, using [MediaQuery.of], or its associated "...Of" methods
+/// are a more appropriate way of obtaining the information that a [FlutterView]
+/// exposes. For example, using [MediaQuery.sizeOf] 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]
+/// attribute (obtained from [MediaQuery.paddingOf]) 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
@@ -123,9 +124,10 @@ class View extends StatelessWidget {
   /// 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
-  /// 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.
+  /// change their values. To access the property values of a [FlutterView]
+  /// prefer using the access methods on [MediaQuery], such as
+  /// [MediaQuery.sizeOf], which will ensure that the `context` is informed when
+  /// the view properties change.
   ///
   /// See also:
   ///