Add more breadcrumbs around material buttons and ink wells. (#9760)

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

@@ -61,7 +61,7 @@ class BackButton extends StatelessWidget {
   }
 }
 
-/// A Material Design close button.
+/// A material design close button.
 ///
 /// A [CloseButton] is an [IconButton] with a "close" icon. When pressed, the
 /// close button calls [Navigator.maybePop] to return to the previous route.
@@ -76,6 +76,7 @@ class BackButton extends StatelessWidget {
 ///  * [BackButton], which is more appropriate for middle nodes in the
 ///    navigation tree or where pages can be popped instantaneously with
 ///    no user data consequence.
+///  * [IconButton], to create other material design icon buttons.
 class CloseButton extends StatelessWidget {
   /// Creates a Material Design close button.
   const CloseButton({ Key key }) : super(key: key);
@@ -84,7 +85,7 @@ class CloseButton extends StatelessWidget {
   Widget build(BuildContext context) {
     return new IconButton(
       icon: const Icon(Icons.close),
-      tooltip: 'Close',
+      tooltip: 'Close', // TODO(ianh): Figure out how to localize this string
       onPressed: () {
         Navigator.of(context).maybePop();
       },

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

@@ -20,9 +20,9 @@ import 'theme.dart';
 ///
 /// See also:
 ///
-///  * [ButtonTheme]
-///  * [RaisedButton]
-///  * [FlatButton]
+///  * [ButtonTheme], which uses this enum to define the [ButtonTheme.textTheme].
+///  * [RaisedButton], which styles itself based on the ambient [ButtonTheme].
+///  * [FlatButton], which styles itself based on the ambient [ButtonTheme].
 enum ButtonTextTheme {
   /// The button should use the normal color (e.g., black or white depending on the [ThemeData.brightness]) for its text.
   normal,
@@ -35,9 +35,9 @@ enum ButtonTextTheme {
 ///
 /// See also:
 ///
-///  * [ButtonTextTheme]
-///  * [RaisedButton]
-///  * [FlatButton]
+///  * [ButtonTextTheme], which is used by [textTheme].
+///  * [RaisedButton], which styles itself based on the ambient [ButtonTheme].
+///  * [FlatButton], which styles itself based on the ambient [ButtonTheme].
 class ButtonTheme extends InheritedWidget {
   /// Creates a button theme.
   ///
@@ -121,6 +121,13 @@ class ButtonTheme extends InheritedWidget {
 ///
 /// MaterialButtons whose [onPressed] handler is null will be disabled. To have
 /// an enabled button, make sure to pass a non-null value for onPressed.
+///
+/// If you want an ink-splash effect for taps, but don't want to use a button,
+/// consider using [InkWell] directly.
+///
+/// See also:
+///
+///  * [IconButton], to create buttons that contain icons rather than text.
 class MaterialButton extends StatefulWidget {
   /// Creates a material button.
   ///

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

@@ -40,6 +40,7 @@ import 'theme.dart';
 ///    material.
 ///  * [DropdownButton], which offers the user a choice of a number of options.
 ///  * [SimpleDialogOption], which is used in [SimpleDialog]s.
+///  * [IconButton], to create buttons that just contain icons.
 ///  * [InkWell], which implements the ink splash part of a flat button.
 ///  * <https://material.google.com/components/buttons.html>
 class FlatButton extends StatelessWidget {

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

@@ -23,7 +23,7 @@ const double _kMinButtonSize = 48.0;
 /// A material design icon button.
 ///
 /// An icon button is a picture printed on a [Material] widget that reacts to
-/// touches by filling with color.
+/// touches by filling with color (ink).
 ///
 /// Icon buttons are commonly used in the [AppBar.actions] field, but they can
 /// be used in many other places as well.
@@ -33,12 +33,19 @@ const double _kMinButtonSize = 48.0;
 ///
 /// Requires one of its ancestors to be a [Material] widget.
 ///
-/// Will be automatically sized up to the recommended 48 logical pixels if smaller.
+/// The hit region of an icon button will, if possible, be at least 48.0 pixels
+/// in size, regardless of the actual [iconSize]. The [alignment] controls how
+/// the icon itself is positioned within the hit region.
 ///
 /// See also:
 ///
-///  * [Icons]
-///  * [AppBar]
+///  * [Icons], a library of predefined icons.
+///  * [BackButton], an icon button for a "back" affordance which adapts to the
+///    current platform's conventions.
+///  * [CloseButton], an icon button for closing pages.
+///  * [AppBar], to show a toolbar at the top of an application.
+///  * [RaisedButton] and [FlatButton], for buttons with text in them.
+///  * [InkResponse] and [InkWell], for the ink splash effect itself.
 class IconButton extends StatelessWidget {
   /// Creates an icon button.
   ///

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

@@ -26,7 +26,15 @@ import 'theme.dart';
 /// If a Widget uses this class directly, it should include the following line
 /// at the top of its [build] function to call [debugCheckHasMaterial]:
 ///
-///     assert(debugCheckHasMaterial(context));
+/// ```dart
+/// assert(debugCheckHasMaterial(context));
+/// ```
+///
+/// See also:
+///
+///  * [GestureDetector], for listening for gestures without ink splashes.
+///  * [RaisedButton] and [FlatButton], two kinds of buttons in material design.
+///  * [IconButton], which combines [InkResponse] with an [Icon].
 class InkResponse extends StatefulWidget {
   /// Creates an area of a [Material] that responds to touch.
   ///
@@ -248,7 +256,16 @@ class _InkResponseState<T extends InkResponse> extends State<T> {
 /// If a Widget uses this class directly, it should include the following line
 /// at the top of its [build] function to call [debugCheckHasMaterial]:
 ///
-///     assert(debugCheckHasMaterial(context));
+/// ```dart
+/// assert(debugCheckHasMaterial(context));
+/// ```
+///
+/// See also:
+///
+///  * [GestureDetector], for listening for gestures without ink splashes.
+///  * [RaisedButton] and [FlatButton], two kinds of buttons in material design.
+///  * [InkResponse], a variant of [InkWell] that doesn't force a rectangular
+///    shape on the ink reaction.
 class InkWell extends InkResponse {
   /// Creates an ink well.
   ///

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

@@ -25,11 +25,16 @@ import 'theme.dart';
 ///
 /// Requires one of its ancestors to be a [Material] widget.
 ///
+/// If you want an ink-splash effect for taps, but don't want to use a button,
+/// consider using [InkWell] directly.
+///
 /// See also:
 ///
-///  * [FlatButton]
-///  * [DropdownButton]
-///  * [FloatingActionButton]
+///  * [FlatButton], a material design button without a shadow.
+///  * [DropdownButton], a button that shows options to select from.
+///  * [FloatingActionButton], the round button in material applications.
+///  * [IconButton], to create buttons that just contain icons.
+///  * [InkWell], which implements the ink splash part of a flat button.
 ///  * <https://material.google.com/components/buttons.html>
 class RaisedButton extends StatelessWidget {
   /// Creates a raised button.

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

@@ -15,7 +15,7 @@ export 'package:flutter/services.dart' show TextInputType;
 const Duration _kTransitionDuration = const Duration(milliseconds: 200);
 const Curve _kTransitionCurve = Curves.fastOutSlowIn;
 
-/// A Material Design text field.
+/// A material design text field.
 ///
 /// A text field lets the user enter text, either with hardware keyboard or with
 /// an onscreen keyboard.

packages/flutter/lib/src/widgets/gesture_detector.dart

@@ -52,7 +52,11 @@ typedef GestureRecognizer GestureRecognizerFactory(GestureRecognizer recognizer)
 /// them to the callbacks. To ignore accessibility events, set
 /// [excludeFromSemantics] to true.
 ///
-/// See http://flutter.io/gestures/ for additional information.
+/// See <http://flutter.io/gestures/> for additional information.
+///
+/// Material design applications typically react to touches with ink splash
+/// effects. The [InkWell] class implements this effect and can be used in place
+/// of a [GestureDetector] for handling taps.
 class GestureDetector extends StatelessWidget {
   /// Creates a widget that detects gestures.
   ///