From 8a5c22e282db5f45ffdef24752520894f18227b9 Mon Sep 17 00:00:00 2001
From: fzyzcjy <5236035+fzyzcjy@users.noreply.github.com>
Date: Thu, 8 Jun 2023 01:04:03 +0800
Subject: [PATCH] Super tiny MediaQuery doc update (#127904)

Just now I see some good news: https://www.reddit.com/r/FlutterDev/comments/13vo5a2/the_most_important_flutter_310_feature_that/ (ignore the title though...). It was a performance problem in the old days, so it was great that the problem disappears. However, it seems that the doc is not updated yet, so everyone reading MediaQuery page will still use the old way. Thus I create this super-tiny PR :)
---
 .../flutter/lib/src/widgets/media_query.dart  | 24 ++++++++++++-------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/packages/flutter/lib/src/widgets/media_query.dart b/packages/flutter/lib/src/widgets/media_query.dart
index f7b554ae08..8cd8ee3c2a 100644
--- a/packages/flutter/lib/src/widgets/media_query.dart
+++ b/packages/flutter/lib/src/widgets/media_query.dart
@@ -756,16 +756,24 @@ class MediaQueryData {
 /// Establishes a subtree in which media queries resolve to the given data.
 ///
 /// For example, to learn the size of the current media (e.g., the window
-/// containing your app), you can read the [MediaQueryData.size] property from
-/// the [MediaQueryData] returned by [MediaQuery.of]:
-/// `MediaQuery.of(context).size`.
+/// containing your app), you can use [MediaQuery.sizeOf]:
+/// `MediaQuery.sizeOf(context)`.
 ///
-/// Querying the current media using [MediaQuery.of] will cause your widget to
-/// rebuild automatically whenever the [MediaQueryData] changes (e.g., if the
-/// user rotates their device).
+/// Querying the current media using specific methods (for example,
+/// [MediaQuery.sizeOf] and [MediaQuery.paddingOf]) will cause your widget to
+/// rebuild automatically whenever the property you query changes.
 ///
-/// If no [MediaQuery] is in scope then the [MediaQuery.of] method will throw an
-/// exception. Alternatively, [MediaQuery.maybeOf] may be used, which returns
+/// On the other hand, querying using [MediaQuery.of] will cause your widget to
+/// rebuild automatically whenever any field of the [MediaQueryData] changes
+/// (e.g., if the user rotates their device). Therefore, if you are only
+/// concerned with one or a few fields of [MediaQueryData], prefer using
+/// the specific methods (for example: [MediaQuery.sizeOf] and
+/// [MediaQuery.paddingOf]).
+///
+/// If no [MediaQuery] is in scope then the series of methods like
+/// [MediaQuery.of] and [MediaQuery.sizeOf] will throw an exception.
+/// Alternatively, the "maybe-" variant methods (such as [MediaQuery.maybeOf]
+/// and [MediaQuery.maybeSizeOf]) can be used, which returns
 /// null instead of throwing if no [MediaQuery] is in scope.
 ///
 /// {@youtube 560 315 https://www.youtube.com/watch?v=A3WrA4zAaPw}