From a6aa4888c8ffa0db1b3c95650e30ccf6a85a4a03 Mon Sep 17 00:00:00 2001
From: Ian Hickson <ian@hixie.ch>
Date: Mon, 31 May 2021 14:54:19 -0700
Subject: [PATCH] Clarify the IconTheme documentation

---
 packages/flutter/lib/src/widgets/icon.dart       |  9 +++++----
 packages/flutter/lib/src/widgets/icon_theme.dart | 13 +++++++++++--
 packages/flutter/lib/src/widgets/image_icon.dart |  2 +-
 3 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/packages/flutter/lib/src/widgets/icon.dart b/packages/flutter/lib/src/widgets/icon.dart
index b0728a3f7e262a..dd97ffeae8556c 100644
--- a/packages/flutter/lib/src/widgets/icon.dart
+++ b/packages/flutter/lib/src/widgets/icon.dart
@@ -100,21 +100,22 @@ class Icon extends StatelessWidget {
   ///
   /// Defaults to the current [IconTheme] color, if any.
   ///
-  /// The given color will be adjusted by the opacity of the current
+  /// The color (whether specified explicitly here or obtained from the
+  /// [IconTheme]) will be further adjusted by the opacity of the current
   /// [IconTheme], if any.
   ///
-  ///
   /// In material apps, if there is a [Theme] without any [IconTheme]s
   /// specified, icon colors default to white if the theme is dark
   /// and black if the theme is light.
   ///
-  /// If no [IconTheme] and no [Theme] is specified, icons will default to black.
+  /// If no [IconTheme] and no [Theme] is specified, icons will default to
+  /// black.
   ///
   /// See [Theme] to set the current theme and [ThemeData.brightness]
   /// for setting the current theme's brightness.
   ///
   /// {@tool snippet}
-  /// Typically, a material design color will be used, as follows:
+  /// Typically, a Material Design color will be used, as follows:
   ///
   /// ```dart
   /// Icon(
diff --git a/packages/flutter/lib/src/widgets/icon_theme.dart b/packages/flutter/lib/src/widgets/icon_theme.dart
index 1da6d19e670186..e4ffdb61eb192f 100644
--- a/packages/flutter/lib/src/widgets/icon_theme.dart
+++ b/packages/flutter/lib/src/widgets/icon_theme.dart
@@ -49,9 +49,18 @@ class IconTheme extends InheritedTheme {
   final IconThemeData data;
 
   /// The data from the closest instance of this class that encloses the given
-  /// context.
+  /// context, if any.
   ///
-  /// Defaults to the current [ThemeData.iconTheme].
+  /// If there is no ambient icon theme, defaults to [IconThemeData.fallback].
+  /// The returned [IconThemeData] is concrete (all values are non-null; see
+  /// [IconThemeData.isConcrete]). Any properties on the ambient icon theme that
+  /// are null get defaulted to the values specified on
+  /// [IconThemeData.fallback].
+  ///
+  /// The [Theme] widget from the `material` library introduces an [IconTheme]
+  /// widget set to the [ThemeData.iconTheme], so in a Material Design
+  /// application, this will typically default to the icon theme from the
+  /// ambient [Theme].
   ///
   /// Typical usage is as follows:
   ///
diff --git a/packages/flutter/lib/src/widgets/image_icon.dart b/packages/flutter/lib/src/widgets/image_icon.dart
index 1b9cea9104b3e0..3eb9746124e4f1 100644
--- a/packages/flutter/lib/src/widgets/image_icon.dart
+++ b/packages/flutter/lib/src/widgets/image_icon.dart
@@ -51,7 +51,7 @@ class ImageIcon extends StatelessWidget {
   /// Defaults to the current [IconTheme] color, if any. If there is
   /// no [IconTheme], then it defaults to not recolorizing the image.
   ///
-  /// The image will additionally be adjusted by the opacity of the current
+  /// The image will be additionally adjusted by the opacity of the current
   /// [IconTheme], if any.
   final Color? color;