Theme doc improvements (#6585)

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

@@ -73,7 +73,7 @@ class DrawerItem extends StatelessWidget {
           return themeData.accentColor;
         if (onPressed == null)
           return Colors.white30;
-        return null; // use default icon theme colour unmodified
+        return null; // use default icon theme color unmodified
     }
     assert(themeData.brightness != null);
     return null;

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

@@ -9,16 +9,24 @@ import 'theme_data.dart';
 
 export 'theme_data.dart' show Brightness, ThemeData;
 
-/// The duration over which theme changes animate.
+/// The duration over which theme changes animate by default.
 const Duration kThemeAnimationDuration = const Duration(milliseconds: 200);
 
 /// Applies a theme to descendant widgets.
 ///
+/// A theme describes the colors and typographic choices of an application.
+///
+/// Descendant widgets obtain the current theme's [ThemeData] object using
+/// [Theme.of]. When a widget uses [Theme.of], it is automatically rebuilt if
+/// the theme later changes, so that the changes can be applied.
+///
 /// See also:
 ///
-///  * [AnimatedTheme]
-///  * [ThemeData]
-///  * [MaterialApp]
+///  * [ThemeData], which describes the actual configuration of a theme.
+///  * [AnimatedTheme], which animates the [ThemeData] when it changes rather
+///    than changing the theme all at once.
+///  * [MaterialApp], which includes an [AnimatedTheme] widget configured via
+///    the [MaterialApp.theme] argument.
 class Theme extends InheritedWidget {
   /// Applies the given theme [data] to [child].
   ///
@@ -49,16 +57,19 @@ class Theme extends InheritedWidget {
 
   static final ThemeData _kFallbackTheme = new ThemeData.fallback();
 
-  /// The data from the closest instance of this class that encloses the given context.
+  /// The data from the closest [Theme] instance that encloses the given
+  /// context.
   ///
-  /// Defaults to the fallback theme data if none exists.
+  /// Defaults to [new ThemeData.fallback] if there is no [Theme] in the given
+  /// build context.
   ///
-  /// If [shadowThemeOnly] is true and the closest Theme ancestor was installed by
-  /// the [MaterialApp] - in other words if the closest Theme ancestor does not
-  /// shadow the app's theme - then return null. This property is specified in
-  /// situations where its useful to wrap a route's widgets with a Theme, but only
-  /// when the app's theme is being shadowed by a theme widget that is farather
-  /// down in the tree. See [isMaterialAppTheme].
+  /// If [shadowThemeOnly] is true and the closest [Theme] ancestor was
+  /// installed by the [MaterialApp] — in other words if the closest [Theme]
+  /// ancestor does not shadow the application's theme — then this returns null.
+  /// This argument should be used in situations where its useful to wrap a
+  /// route's widgets with a [Theme], but only when the application's overall
+  /// theme is being shadowed by a [Theme] widget that is deeper in the tree.
+  /// See [isMaterialAppTheme].
   ///
   /// Typical usage is as follows:
   ///
@@ -128,12 +139,16 @@ class ThemeDataTween extends Tween<ThemeData> {
   ThemeData lerp(double t) => ThemeData.lerp(begin, end, t);
 }
 
-/// Animated version of [Theme] which automatically transitions the colours,
+/// Animated version of [Theme] which automatically transitions the colors,
 /// etc, over a given duration whenever the given theme changes.
 ///
 /// See also:
 ///
-///  * [ThemeData]
+///  * [Theme], which [AnimatedTheme] uses to actually apply the interpolated
+///    theme.
+///  * [ThemeData], which describes the actual configuration of a theme.
+///  * [MaterialApp], which includes an [AnimatedTheme] widget configured via
+///    the [MaterialApp.theme] argument.
 class AnimatedTheme extends ImplicitlyAnimatedWidget {
   /// Creates an animated theme.
   ///

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

@@ -45,6 +45,8 @@ const Color _kDarkThemeSplashColor = const Color(0x40CCCCCC);
 /// Holds the color and typography values for a material design theme.
 ///
 /// Use this class to configure a [Theme] widget.
+///
+/// To obtain the current theme, use [Theme.of].
 class ThemeData {
   /// Create a ThemeData given a set of preferred values.
   ///