Document the onPressed/disabled behavior.

Fixes https://github.com/flutter/flutter/issues/1331

Hopefully this will be enough to start with. If this continues to be a
point of confusion we can see about adding more documentation or
changing the API somehow.

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

@@ -7,6 +7,28 @@ import 'package:flutter/widgets.dart';
 import 'material_button.dart';
 import 'theme.dart';
 
+/// A material design "flat button".
+///
+/// A flat button is a section printed on a [Material] widget that reacts to
+/// touches by filling with color.
+///
+/// Use flat buttons on toolbars, in dialogs, or inline with other content but
+/// offset from that content with padding so that the button's presence is
+/// obvious. Flat buttons intentionally do not have visible borders and must
+/// therefore rely on their position relative to other content for context. In
+/// dialogs and cards, they should be grouped together in one of the bottom
+/// corners. Avoid using flat buttons where they would blend in with other
+/// content, for example in the middle of lists.
+///
+/// If the [onPressed] callback is not specified or null, then the button will
+/// be disabled, will not react to touch, and will be colored as specified by
+/// the [disabledColor] property instead of the [color] property. If you are
+/// trying to change the button's [color] and it is not having any effect, check
+/// that you are passing a non-null [onPressed] handler.
+///
+/// See also:
+///  * [RaisedButton] class
+///  * https://www.google.com/design/spec/components/buttons.html
 class FlatButton extends MaterialButton {
   FlatButton({
     Key key,
@@ -25,8 +47,13 @@ class FlatButton extends MaterialButton {
              disabledTextColor: disabledTextColor,
              onPressed: onPressed);
 
-  // These default to null, meaning transparent.
+  /// The color of the button, as printed on the [Material]. Defaults to null,
+  /// meaning transparent.
   final Color color;
+
+  /// The color of the button when the button is disabled. Buttons are disabled
+  /// by default. To enable a button, set its [onPressed] property to a non-null
+  /// value.
   final Color disabledColor;
 
   /// Controls the default text color if the text color isn't explicit set.

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

@@ -17,6 +17,20 @@ const double _kSizeMini = 40.0;
 const Duration _kChildSegue = const Duration(milliseconds: 400);
 const Interval _kChildSegueInterval = const Interval(0.65, 1.0);
 
+/// A material design "floating action button".
+///
+/// A floating action button is a circular icon button that hovers over content
+/// to promote a primary action in the application.
+///
+/// Use at most a single floating action button per screen. Floating action
+/// buttons should be used for positive actions such as "create", "share", or
+/// "navigate".
+///
+/// If the [onPressed] callback is not specified or null, then the button will
+/// be disabled, will not react to touch.
+///
+/// See also:
+///  * https://www.google.com/design/spec/components/buttons-floating-action-button.html
 class FloatingActionButton extends StatefulComponent {
   const FloatingActionButton({
     Key key,
@@ -30,6 +44,10 @@ class FloatingActionButton extends StatefulComponent {
 
   final Widget child;
   final Color backgroundColor;
+
+  /// The callback that is invoked when the button is tapped or otherwise activated.
+  ///
+  /// If this is set to null, the button will be disabled.
   final VoidCallback onPressed;
   final int elevation;
   final int highlightElevation;

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

@@ -9,6 +9,15 @@ import 'icon_theme_data.dart';
 import 'ink_well.dart';
 import 'tooltip.dart';
 
+/// A material design "icon button".
+///
+/// An icon button is a picture printed on a [Material] widget that reacts to
+/// touches by filling with color.
+///
+/// Use icon buttons on toolbars.
+///
+/// If the [onPressed] callback is not specified or null, then the button will
+/// be disabled, will not react to touch.
 class IconButton extends StatelessComponent {
   const IconButton({
     Key key,
@@ -22,6 +31,10 @@ class IconButton extends StatelessComponent {
   final String icon;
   final IconThemeColor colorTheme;
   final Color color;
+
+  /// The callback that is invoked when the button is tapped or otherwise activated.
+  ///
+  /// If this is set to null, the button will be disabled.
   final VoidCallback onPressed;
   final String tooltip;
 

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

@@ -35,7 +35,10 @@ class ButtonTheme extends InheritedWidget {
 }
 
 /// Base class for buttons in the Material theme.
-/// Rather than using this class directly, please use FlatButton or RaisedButton.
+/// Rather than using this class directly, please use [FlatButton] or [RaisedButton].
+///
+/// MaterialButtons whose [onPressed] handler is null will be disabled. To have
+/// an enabled button, make sure to pass a non-null value for onPressed.
 abstract class MaterialButton extends StatefulComponent {
   MaterialButton({
     Key key,
@@ -50,8 +53,14 @@ abstract class MaterialButton extends StatefulComponent {
   final ButtonColor textTheme;
   final Color textColor;
   final Color disabledTextColor;
+
+  /// The callback that is invoked when the button is tapped or otherwise activated.
+  ///
+  /// If this is set to null, the button will be disabled.
   final VoidCallback onPressed;
 
+  /// Whether the button is enabled or disabled. Buttons are disabled by default. To
+  /// enable a button, set its [onPressed] property to a non-null value.
   bool get enabled => onPressed != null;
 
   void debugFillDescription(List<String> description) {

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

@@ -8,6 +8,24 @@ import 'colors.dart';
 import 'material_button.dart';
 import 'theme.dart';
 
+/// A material design "raised button".
+///
+/// A raised button consists of a rectangular piece of material that hovers over
+/// the interface.
+///
+/// Use raised buttons to add dimension to otherwise mostly flat layouts, e.g.
+/// in long busy lists of content, or in wide spaces. Avoid using raised buttons
+/// on already-raised content such as dialogs or cards.
+///
+/// If the [onPressed] callback is not specified or null, then the button will
+/// be disabled and by default will appear like a flat button in the
+/// [disabledColor]. If you are trying to change the button's [color] and it is
+/// not having any effect, check that you are passing a non-null [onPressed]
+/// handler.
+///
+/// See also:
+///  * [FlatButton] class
+///  * https://www.google.com/design/spec/components/buttons.html
 class RaisedButton extends MaterialButton {
   RaisedButton({
     Key key,
@@ -23,7 +41,13 @@ class RaisedButton extends MaterialButton {
              child: child,
              onPressed: onPressed);
 
+  /// The color of the button, as printed on the [Material]. Defaults to null,
+  /// meaning that the color is automatically derived from the [Theme].
   final Color color;
+
+  /// The color of the button when the button is disabled. Buttons are disabled
+  /// by default. To enable a button, set its [onPressed] property to a non-null
+  /// value.
   final Color disabledColor;
 
   /// Controls the default text color if the text color isn't explicit set.

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

@@ -30,12 +30,23 @@ const Duration kSnackBarMediumDisplayDuration = const Duration(milliseconds: 275
 const Curve _snackBarHeightCurve = Curves.fastOutSlowIn;
 const Curve _snackBarFadeCurve = const Interval(0.72, 1.0, curve: Curves.fastOutSlowIn);
 
+/// A button for a [SnackBar], known as an "action".
+///
+/// Snack bar actions are always enabled. If you want to disable a snack bar
+/// action, simply don't include it in the snack bar.
+///
+/// See also:
+///  * https://www.google.com/design/spec/components/snackbars-toasts.html
 class SnackBarAction extends StatelessComponent {
   SnackBarAction({Key key, this.label, this.onPressed }) : super(key: key) {
     assert(label != null);
+    assert(onPressed != null);
   }
 
+  /// The button label.
   final String label;
+
+  /// The callback to be invoked when the button is pressed. Must be non-null.
   final VoidCallback onPressed;
 
   Widget build(BuildContext context) {
@@ -50,6 +61,15 @@ class SnackBarAction extends StatelessComponent {
   }
 }
 
+/// A lightweight message with an optional action which briefly displays at the
+/// bottom of the screen.
+///
+/// Displayed with the Scaffold.of().showSnackBar() API.
+///
+/// See also:
+///  * [Scaffold.of] and [ScaffoldState.showSnackBar]
+///  * [SnackBarAction]
+///  * https://www.google.com/design/spec/components/snackbars-toasts.html
 class SnackBar extends StatelessComponent {
   SnackBar({
     Key key,