Talk about how to resize IconButtons more. (#7595)

Answers http://stackoverflow.com/questions/41729278/why-is-this-icon-being-clipped

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

@@ -14,17 +14,15 @@ import 'theme.dart';
 ///
 /// Icons are not interactive. For an interactive icon, consider [IconButton].
 ///
-/// Icons are identified by their name (as given on that page), with
-/// spaces converted to underscores, from the [Icons] class. For
-/// example, the "alarm add" icon is [Icons.alarm_add].
+/// Icons are identified by their name (as given on that page), with spaces
+/// converted to underscores, from the [Icons] class. For example, the "alarm
+/// add" icon is [Icons.alarm_add].
 ///
-/// Available icons are shown on this page:
-/// <https://design.google.com/icons/>
+/// Available icons are shown on this page: <https://design.google.com/icons/>
 ///
-/// To use this class, make sure you set `uses-material-design: true`
-/// 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.
+/// To use this class, make sure you set `uses-material-design: true` 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:
 ///
@@ -55,6 +53,11 @@ class Icon extends StatelessWidget {
   /// Defaults to the current [IconTheme] size, if any. If there is no
   /// [IconTheme], or it does not specify an explicit size, then it defaults to
   /// 24.0.
+  ///
+  /// If this [Icon] is being placed inside an [IconButton], then use
+  /// [IconButton.size] instead, so that the [IconButton] can make the splash
+  /// area the appropriate size as well. The [IconButton] uses an [IconTheme] to
+  /// pass down the size to the [Icon].
   final double size;
 
   /// The color to use when drawing the icon.

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

@@ -62,6 +62,13 @@ class IconButton extends StatelessWidget {
   /// The size of the icon inside the button.
   ///
   /// This property must not be null. It defaults to 24.0.
+  ///
+  /// The size given here is passed down to the widget in the [icon] property
+  /// via an [IconTheme]. Setting the size here instead of in, for example, the
+  /// [Icon.size] property allows the [IconButton] to size the splash area to
+  /// fit the [Icon]. If you were to set the size of the [Icon] using
+  /// [Icon.size] instead, then the [IconButton] would default to 24.0 and then
+  /// the [Icon] itself would likely get clipped.
   final double size;
 
   /// The padding around the button's icon. The entire padded icon will react
@@ -77,9 +84,9 @@ class IconButton extends StatelessWidget {
 
   /// The icon to display inside the button.
   ///
-  /// The size and color of the icon is configured automatically using an
-  /// [IconTheme] and therefore does not need to be explicitly given in the
-  /// icon widget.
+  /// The [size] and [color] of the icon is configured automatically based on
+  /// the properties of _this_ widget using an [IconTheme] and therefore should
+  /// not be explicitly given in the icon widget.
   ///
   /// This property must not be null.
   ///