Clean up and document icon button color logic

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

@@ -22,6 +22,11 @@ import 'theme.dart';
 /// in your project's `flutter.yaml` file. This ensures that the
 /// MaterialIcons font is included in your application. This font is
 /// used to display the icons.
+///
+/// See also:
+///
+///  * [IconButton], for interactive icons
+///  * [Icons], for the list of available icons for use with this class
 class Icon extends StatelessWidget {
   Icon({
     Key key,
@@ -41,6 +46,12 @@ class Icon extends StatelessWidget {
   final IconData icon;
 
   /// The color to use when drawing the icon.
+  ///
+  /// Defaults to the current [IconTheme] color, if any. If there is
+  /// no [IconTheme], then it defaults to white if the theme is dark
+  /// and black if the theme is light. See [Theme] to set the current
+  /// theme and [ThemeData.brightness] for setting the current theme's
+  /// brightness.
   final Color color;
 
   Color _getDefaultColorForThemeBrightness(ThemeBrightness brightness) {

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

@@ -20,12 +20,18 @@ import 'tooltip.dart';
 ///
 /// If the [onPressed] callback is not specified or null, then the button will
 /// be disabled, will not react to touch.
+///
+/// See also:
+///
+///  * [Icons]
+///  * [AppBar]
 class IconButton extends StatelessWidget {
   const IconButton({
     Key key,
     this.size: 24.0,
     this.icon,
     this.color,
+    this.disabledColor,
     this.onPressed,
     this.tooltip
   }) : super(key: key);
@@ -39,9 +45,22 @@ class IconButton extends StatelessWidget {
   /// The icon to display inside the button.
   final IconData icon;
 
-  /// The color to use for the icon inside the button.
+  /// The color to use for the icon inside the button, if the icon is enabled.
+  /// Defaults to the current color, as defined by [Icon.color].
+  ///
+  /// The icon is enabled if [onPressed] is not null.
+  ///
+  /// See also [disabledColor].
   final Color color;
 
+  /// The color to use for the icon inside the button, if the icon is disabled.
+  /// Defaults to the [ThemeData.disabledColor] of the current [Theme].
+  ///
+  /// The icon is disabled if [onPressed] is null.
+  ///
+  /// See also [color].
+  final Color disabledColor;
+
   /// The callback that is invoked when the button is tapped or otherwise activated.
   ///
   /// If this is set to null, the button will be disabled.
@@ -56,12 +75,17 @@ class IconButton extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     assert(debugCheckHasMaterial(context));
+    Color currentColor;
+    if (onPressed != null)
+      currentColor = color;
+    else
+      currentColor = disabledColor ?? Theme.of(context).disabledColor;
     Widget result = new Padding(
       padding: const EdgeInsets.all(8.0),
       child: new Icon(
         size: size,
         icon: icon,
-        color: onPressed != null ? color : Theme.of(context).disabledColor
+        color: currentColor
       )
     );
     if (tooltip != null) {