Add missing dartdocs from material.dart (#3709)

Making progress towards document all public APIs in material.dart. We're still
missing a few odds and ends (as well as missing docs in tabs.dart,
tooltip.dart, and two_level_list.dart).

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

@@ -50,6 +50,14 @@ class ButtonTheme extends InheritedWidget {
     Widget child
   }) : super(key: key, child: child);
 
+  /// Creates a button theme that is appropriate for footer buttons.
+  ///
+  /// This theme is denser, with a smaller [minWidth] and [padding], than the
+  /// default theme. Also, this theme uses [ButtonTextTheme.accent] rather than
+  /// [ButtonTextTheme.normal].
+  ///
+  /// For example, buttons at the bottom of [Dialog] or [Card] widgets use this
+  /// button theme.
   const ButtonTheme.footer({
     Key key,
     this.textTheme: ButtonTextTheme.accent,

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

@@ -6,8 +6,6 @@ import 'package:flutter/widgets.dart';
 
 import 'material.dart';
 
-const EdgeInsets _kCardMargins = const EdgeInsets.all(4.0);
-
 /// A material design card
 ///
 /// See also:
@@ -16,7 +14,12 @@ const EdgeInsets _kCardMargins = const EdgeInsets.all(4.0);
 ///  * [showDialog]
 ///  * <https://www.google.com/design/spec/components/cards.html>
 class Card extends StatelessWidget {
-  const Card({ Key key, this.child, this.color }) : super(key: key);
+  /// Creates a material design card.
+  const Card({
+    Key key,
+    this.child,
+    this.color
+  }) : super(key: key);
 
   /// The widget below this widget in the tree.
   final Widget child;
@@ -27,7 +30,7 @@ class Card extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     return new Container(
-      margin: _kCardMargins,
+      margin: const EdgeInsets.all(4.0),
       child: new Material(
         color: color,
         type: MaterialType.card,

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

@@ -21,10 +21,9 @@ import 'theme.dart';
 import 'theme_data.dart';
 import 'tooltip.dart';
 
+/// Signature for [DataColumn.onSort] callback.
 typedef void DataColumnSortCallback(int columnIndex, bool ascending);
 
-typedef void DataCellEditCallback(Rect cell);
-
 /// Column configuration for a [DataTable].
 ///
 /// One column configuration must be provided for each column to
@@ -215,7 +214,7 @@ class DataTable extends StatelessWidget {
   /// objects as the table is to have columns, ignoring the leading
   /// checkbox column if any. The [columns] argument must have a
   /// length greater than zero.
-  /// 
+  ///
   /// The [rows] argument must be a list of as many [DataRow] objects
   /// as the table is to have rows, ignoring the leading heading row
   /// that contains the column headings (derived from the [columns]
@@ -563,6 +562,7 @@ class DataTable extends StatelessWidget {
 /// achieve: just put the TableRowInkWell as the direct child of the
 /// [Table], and put the other contents of the cell inside it.)
 class TableRowInkWell extends InkResponse {
+  /// Creates an ink well for a table row.
   TableRowInkWell({
     Key key,
     Widget child,
@@ -700,7 +700,7 @@ class _SortArrowState extends State<_SortArrow> {
       if (config.visible) {
         _opacityController.forward();
       } else {
-        _opacityController.reverse();   
+        _opacityController.reverse();
       }
     }
     if ((_down != newDown) && !skipArrow) {
@@ -741,26 +741,3 @@ class _SortArrowState extends State<_SortArrow> {
   }
 
 }
-
-/* 
-
-TODO(ianh): implement DataTableCard
-
-DataTableCard
- - top: 64px
-   - caption, top left
-      - 20px Roboto Regular, black87
-   - persistent actions, top left
-   - header when there's a selection
-      - accent 50?
-      - show number of selected items
-      - different actions
-   - actions, top right
-      - 24px icons, black54
-
-bottom:
- - 56px
- - handles pagination
-    - 12px Roboto Regular, black54
-
-*/

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

@@ -449,6 +449,12 @@ class _MonthPickerState extends State<MonthPicker> {
 ///  * [DatePicker]
 ///  * <https://www.google.com/design/spec/components/pickers.html#pickers-date-pickers>
 class YearPicker extends StatefulWidget {
+  /// Creates a year picker.
+  ///
+  /// The [selectedDate] and [onChanged] arguments must not be null. The
+  /// [lastDate] must be after the [firstDate].
+  ///
+  /// Rarely used directly. Instead, typically used as part of a [DatePicker].
   YearPicker({
     Key key,
     this.selectedDate,

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

@@ -74,26 +74,43 @@ class Drawer extends StatelessWidget {
 
 /// Provides interactive behavior for [Drawer] widgets.
 ///
-/// Drawer controllers are typically created automatically by [Scaffold]
-/// widgets.
+/// Rarely used directly. Drawer controllers are typically created automatically
+/// by [Scaffold] widgets.
+///
+/// The draw controller provides the ability to open and close a drawer, either
+/// via an animation or via user interaction. When closed, the drawer collapses
+/// to a translucent gesture detector that can be used to listen for edge
+/// swipes.
 ///
 /// See also:
 ///
-/// * [Drawer]
-/// * [Scaffold.drawer]
+///  * [Drawer]
+///  * [Scaffold.drawer]
 class DrawerController extends StatefulWidget {
+  /// Creates a controller for a [Drawer].
+  ///
+  /// Rarely used directly.
+  ///
+  /// The [child] argument must not be null and is typically a [Drawer].
   DrawerController({
     GlobalKey key,
     this.child
-  }) : super(key: key);
+  }) : super(key: key) {
+    assert(child != null);
+  }
 
   /// The widget below this widget in the tree.
+  ///
+  /// Typically a [Drawer].
   final Widget child;
 
   @override
   DrawerControllerState createState() => new DrawerControllerState();
 }
 
+/// State for a [DrawerController].
+///
+/// Typically used by a [Scaffold] to [open] and [close] the drawer.
 class DrawerControllerState extends State<DrawerController> {
   @override
   void initState() {
@@ -194,10 +211,14 @@ class DrawerControllerState extends State<DrawerController> {
     }
   }
 
+  /// Starts an animation to open the drawer.
+  ///
+  /// Typically called by [Scaffold.openDrawer].
   void open() {
     _controller.fling(velocity: 1.0);
   }
 
+  /// Starts an animation to close the drawer.
   void close() {
     _controller.fling(velocity: -1.0);
   }

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

@@ -218,12 +218,21 @@ class _DropDownRoute<T> extends PopupRoute<_DropDownRouteResult<T>> {
   }
 }
 
+/// An item in a menu created by a [DropDownButton].
+///
+/// The type `T` is the type of the value the entry represents. All the entries
+/// in a given menu must represent values with consistent types.
 class DropDownMenuItem<T> extends StatelessWidget {
+  /// Creates an item for a drop down menu.
+  ///
+  /// The [child] argument is required.
   DropDownMenuItem({
     Key key,
     this.value,
     this.child
-  }) : super(key: key);
+  }) : super(key: key) {
+    assert(child != null);
+  }
 
   /// The widget below this widget in the tree.
   final Widget child;
@@ -290,6 +299,9 @@ class DropDownButtonHideUnderline extends InheritedWidget {
 ///  * [FlatButton]
 ///  * <https://www.google.com/design/spec/components/buttons.html#buttons-dropdown-buttons>
 class DropDownButton<T> extends StatefulWidget {
+  /// Creates a drop down button.
+  ///
+  /// The [items] must have distinct values and [value] must be among them.
   DropDownButton({
     Key key,
     this.items,

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

@@ -34,6 +34,10 @@ import 'theme.dart';
 ///  * [DropDownButton]
 ///  * <https://www.google.com/design/spec/components/buttons.html>
 class FlatButton extends StatelessWidget {
+  /// Creates a flat button.
+  ///
+  /// The [child] argument is required and is typically a [Text] widget in all
+  /// caps.
   FlatButton({
     Key key,
     this.onPressed,
@@ -44,7 +48,9 @@ class FlatButton extends StatelessWidget {
     this.textTheme,
     this.colorBrightness,
     this.child
-  }) : super(key: key);
+  }) : super(key: key) {
+    assert(child != null);
+  }
 
   /// The callback that is invoked when the button is tapped or otherwise activated.
   ///
@@ -81,6 +87,8 @@ class FlatButton extends StatelessWidget {
   final ThemeBrightness colorBrightness;
 
   /// The widget below this widget in the tree.
+  ///
+  /// Typically a [Text] widget in all caps.
   final Widget child;
 
   /// Whether the button is enabled or disabled. Buttons are disabled by default. To

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

@@ -25,6 +25,9 @@ const double _kTextSelectionHandleSize = 20.0; // pixels
 ///
 ///  * <https://www.google.com/design/spec/components/text-fields.html>
 class Input extends StatefulWidget {
+  /// Creates a text input field.
+  ///
+  /// By default, the input uses a keyboard appropriate for text entry.
   Input({
     Key key,
     this.value,

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

@@ -87,7 +87,7 @@ abstract class InkHighlight {
   /// Whether this part of the material is being visually emphasized.
   bool get active;
 
-  /// The color use to visually represent the emphasis.
+  /// The color of the ink used to emphasize part of the material.
   Color get color;
   void set color(Color value);
 }

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

@@ -415,8 +415,20 @@ class _RefreshProgressIndicatorPainter extends _CircularProgressIndicatorPainter
   }
 }
 
-
+/// An indicator for the progress of refreshing the contents of a widget.
+///
+/// Typically used for swipe-to-refresh interactions. See [RefreshIndicator] for
+/// a complete implementation of swipe-to-refresh driven by a [Scrollable]
+/// widget.
+///
+/// See also:
+///
+///  * [RefreshIndicator]
 class RefreshProgressIndicator extends CircularProgressIndicator {
+  /// Creates a refresh progress indicator.
+  ///
+  /// Rather than creating a refresh progress indicator directly, consider using
+  /// a [RefreshIndicator] together with a [Scrollable] widget.
   RefreshProgressIndicator({
     Key key,
     double value,

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

@@ -32,6 +32,10 @@ import 'theme.dart';
 ///  * [FloatingActionButton]
 ///  * <https://www.google.com/design/spec/components/buttons.html>
 class RaisedButton extends StatelessWidget {
+  /// Creates a raised button.
+  ///
+  /// The [child] argument is required and is typically a [Text] widget in all
+  /// caps.
   RaisedButton({
     Key key,
     this.onPressed,
@@ -79,6 +83,8 @@ class RaisedButton extends StatelessWidget {
   final ThemeBrightness colorBrightness;
 
   /// The widget below this widget in the tree.
+  ///
+  /// Typically a [Text] widget in all caps.
   final Widget child;
 
   /// Whether the button is enabled or disabled. Buttons are disabled by default. To

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

@@ -36,7 +36,13 @@ typedef Future<Null> RefreshCallback();
 
 /// Where the refresh indicator appears: top for over-scrolls at the
 /// start of the scrollable, bottom for over-scrolls at the end.
-enum RefreshIndicatorLocation { top, bottom }
+enum RefreshIndicatorLocation {
+  /// The refresh indicator should appear at the top of the scrollable.
+  top,
+
+  /// The refresh indicator should appear at the bottom of the scrollable.
+  bottom,
+}
 
 /// A widget that supports the Material "swipe to refresh" idiom.
 ///

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

@@ -703,12 +703,19 @@ class ScaffoldState extends State<Scaffold> {
   }
 }
 
+/// An interface for controlling a feature of a [Scaffold].
+///
+/// Commonly obtained from [Scaffold.showSnackBar] or [Scaffold.showBottomSheet].
 class ScaffoldFeatureController<T extends Widget, U> {
   const ScaffoldFeatureController._(this._widget, this._completer, this.close, this.setState);
   final T _widget;
   final Completer<U> _completer;
   Future<U> get closed => _completer.future;
-  final VoidCallback close; // call this to close the bottom sheet or snack bar
+
+  /// Remove the feature (e.g., bottom sheet or snack bar) from the scaffold.
+  final VoidCallback close;
+
+  /// Mark the feature (e.g., bottom sheet or snack bar) as needing to rebuild.
   final StateSetter setState;
 }
 

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

@@ -26,8 +26,8 @@ const Color _kSnackBackground = const Color(0xFF323232);
 // TODO(ianh): Implement the Tablet version of snackbar if we're "on a tablet".
 
 const Duration _kSnackBarTransitionDuration = const Duration(milliseconds: 250);
-const Duration kSnackBarShortDisplayDuration = const Duration(milliseconds: 1500);
-const Duration kSnackBarMediumDisplayDuration = const Duration(milliseconds: 2750);
+const Duration _kSnackBarShortDisplayDuration = const Duration(milliseconds: 1500);
+const Duration _kSnackBarMediumDisplayDuration = const Duration(milliseconds: 2750);
 const Curve _snackBarHeightCurve = Curves.fastOutSlowIn;
 const Curve _snackBarFadeCurve = const Interval(0.72, 1.0, curve: Curves.fastOutSlowIn);
 
@@ -107,7 +107,7 @@ class SnackBar extends StatelessWidget {
     Key key,
     this.content,
     this.action,
-    this.duration: kSnackBarShortDisplayDuration,
+    this.duration: _kSnackBarShortDisplayDuration,
     this.animation
   }) : super(key: key) {
     assert(content != null);

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

@@ -55,6 +55,7 @@ class Theme extends InheritedWidget {
 
 /// An animated value that interpolates [ThemeData]s.
 class ThemeDataTween extends Tween<ThemeData> {
+  /// Creates an interpolation between [begin] and [end].
   ThemeDataTween({ ThemeData begin, ThemeData end }) : super(begin: begin, end: end);
 
   @override

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

@@ -276,6 +276,7 @@ class ThemeData {
   /// The color of text selections in text fields, such as [Input].
   final Color textSelectionColor;
 
+  /// The color of the handles used to adjust what part of the text is currently selected.
   final Color textSelectionHandleColor;
 
   /// A color that contrasts with the [primaryColor], e.g. used as the
@@ -298,6 +299,7 @@ class ThemeData {
   /// A text theme that contrasts with the primary color.
   final TextTheme primaryTextTheme;
 
+  /// An icon theme that contrasts with the primary color.
   final IconThemeData primaryIconTheme;
 
   /// Linearly interpolate between two themes.

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

@@ -28,6 +28,10 @@ enum DayPeriod {
 
 /// A value representing a time during the day
 class TimeOfDay {
+  /// Creates a time of day.
+  ///
+  /// The [hour] argument must be between 0 and 23, inclusive. The [minute]
+  /// argument must be between 0 and 59, inclusive.
   const TimeOfDay({ this.hour, this.minute });
 
   /// Returns a new TimeOfDay with the hour and/or minute replaced.
@@ -105,6 +109,12 @@ enum _TimePickerMode { hour, minute }
 ///  * [showTimePicker]
 ///  * <https://www.google.com/design/spec/components/pickers.html#pickers-time-pickers>
 class TimePicker extends StatefulWidget {
+  /// Creates a time picker.
+  ///
+  /// The [selectedTime] must not be null.
+  ///
+  /// Rarely used directly. Instead, consider using [showTimePicker], which
+  /// creates a time picker dialog.
   TimePicker({
     Key key,
     this.selectedTime,

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

@@ -11,11 +11,16 @@ import 'constants.dart';
 const Duration _kToggleDuration = const Duration(milliseconds: 200);
 final Tween<double> _kRadialReactionRadiusTween = new Tween<double>(begin: 0.0, end: kRadialReactionRadius);
 
-// RenderToggleable is a base class for material style toggleable controls with
-// toggle animations. It handles storing the current value, dispatching
-// ValueChanged on a tap gesture and driving a changed animation. Subclasses are
-// responsible for painting.
+/// A base class for material style toggleable controls with toggle animations.
+///
+/// This class handles storing the current value, dispatching ValueChanged on a
+/// tap gesture and driving a changed animation. Subclasses are responsible for
+/// painting.
 abstract class RenderToggleable extends RenderConstrainedBox implements SemanticActionHandler {
+  /// Creates a toggleable render object.
+  ///
+  /// The [value], [activeColor], and [inactiveColor] arguments must not be
+  /// null.
   RenderToggleable({
     bool value,
     Size size,