Add more dartdoc to material.dart (#3204)

The dartdoc will continue until morale improves.

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

@@ -12,6 +12,12 @@ import 'tabs.dart';
 import 'theme.dart';
 import 'typography.dart';
 
+// TODO(eseidel) Toolbar needs to change size based on orientation:
+// http://www.google.com/design/spec/layout/structure.html#structure-app-bar
+// Mobile Landscape: 48dp
+// Mobile Portrait: 56dp
+// Tablet/Desktop: 64dp
+
 /// A material design app bar.
 ///
 /// An app bar consists of a tool bar and potentially other widgets, such as a
@@ -19,8 +25,8 @@ import 'typography.dart';
 /// common actions with [IconButtons]s which are optionally followed by a
 /// [PopupMenuButton] for less common operations.
 ///
-/// App bars are most commonly used in a [Scaffold], which places the app bar at
-/// the top of the app.
+/// App bars are most commonly used in the [Scaffold.appBar] property, which
+/// places the app bar at the top of the app.
 ///
 /// See also:
 ///
@@ -31,6 +37,9 @@ import 'typography.dart';
 ///  * [FlexibleSpaceBar]
 ///  * <https://www.google.com/design/spec/layout/structure.html#structure-toolbars>
 class AppBar extends StatelessWidget {
+  /// Creates a material design app bar.
+  ///
+  /// Typically used in the [Scaffold.appBar] property.
   AppBar({
     Key key,
     this.leading,

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

@@ -236,8 +236,7 @@ class _ModalBottomSheetRoute<T> extends PopupRoute<T> {
 /// can be created and displayed with the [Scaffold.showBottomSheet] function.
 ///
 /// Returns a `Future` that resolves to the value (if any) that was passed to
-/// [Navigator.pop] when the modal bottom sheet is removed from the navigation
-/// history.
+/// [Navigator.pop] when the modal bottom sheet was closed.
 ///
 /// See also:
 ///

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

@@ -30,11 +30,17 @@ import 'toggleable.dart';
 ///  * <https://www.google.com/design/spec/components/selection-controls.html#selection-controls-checkbox>
 ///  * <https://www.google.com/design/spec/components/lists-controls.html#lists-controls-types-of-list-controls>
 class Checkbox extends StatelessWidget {
-  /// Constructs a checkbox
+  /// Creates a material design checkbox.
   ///
-  /// * `value` determines whether the checkbox is checked.
-  /// * `onChanged` is called whenever the state of the checkbox should change.
-  const Checkbox({
+  /// The checkbox itself does not maintain any state. Instead, when the state of
+  /// the checkbox changes, the widget calls the [onChanged] callback. Most
+  /// widgets that use a checkbox will listen for the [onChanged] callback and
+  /// rebuild the checkbox with a new [value] to update the visual appearance of
+  /// the checkbox.
+  ///
+  /// * [value] determines whether the checkbox is checked.
+  /// * [onChanged] is called when the value of the checkbox should change.
+  Checkbox({
     Key key,
     this.value,
     this.activeColor,
@@ -49,7 +55,7 @@ class Checkbox extends StatelessWidget {
   /// Defaults to accent color of the current [Theme].
   final Color activeColor;
 
-  /// Called when the user checks or unchecks the checkbox.
+  /// Called when the value of the checkbox should change.
   ///
   /// The checkbox passes the new value to the callback but does not actually
   /// change state until the parent widget rebuilds the checkbox with the new

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

@@ -35,6 +35,10 @@ const TextStyle _kLabelStyle = const TextStyle(
 ///  * [CircleAvatar]
 ///  * <https://www.google.com/design/spec/components/chips.html>
 class Chip extends StatelessWidget {
+  /// Creates a material design chip.
+  ///
+  ///  * [onDeleted] determines whether the chip has a delete button. This
+  ///    callback runs when the delete button is pressed.
   const Chip({
     Key key,
     this.avatar,

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

@@ -19,6 +19,7 @@ import 'theme.dart';
 ///  * [ListItem]
 ///  * <https://www.google.com/design/spec/components/chips.html#chips-contact-chips>
 class CircleAvatar extends StatelessWidget {
+  /// Creates a circle that represents a user.
   CircleAvatar({
     Key key,
     this.child,

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

@@ -2,39 +2,20 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-import 'package:flutter/widgets.dart';
-
-// TODO(eseidel) Toolbar needs to change size based on orientation:
-// http://www.google.com/design/spec/layout/structure.html#structure-app-bar
-// Mobile Landscape: 48dp
-// Mobile Portrait: 56dp
-// Tablet/Desktop: 64dp
+/// The height of the tool bar component of the [AppBar].
 const double kToolBarHeight = 56.0;
-const double kExtendedAppBarHeight = 128.0;
 
+/// The height of a tab bar containing text.
 const double kTextTabBarHeight = 48.0;
-const double kIconTabBarHeight = 26.0;
-const double kTextAndIconTabBarHeight = 74.0;
-
-// https://www.google.com/design/spec/layout/metrics-keylines.html#metrics-keylines-keylines-spacing
-const double kListTitleHeight = 72.0;
-const double kListSubtitleHeight = 48.0;
 
-const double kOneLineListItemHeight = 48.0;
-const double kOneLineListItemWithAvatarHeight = 56.0;
-const double kTwoLineListItemHeight = 72.0;
-const double kThreeLineListItemHeight = 88.0;
-
-const double kMaterialDrawerHeight = 140.0;
-const double kScrollbarSize = 10.0;
-const Duration kScrollbarFadeDuration = const Duration(milliseconds: 250);
-const Duration kScrollbarFadeDelay = const Duration(milliseconds: 300);
-const double kFadingEdgeLength = 12.0;
-const double kPressedStateDuration = 64.0; // units?
+/// The amount of time theme change animations should last.
 const Duration kThemeChangeDuration = const Duration(milliseconds: 200);
 
-const EdgeInsets kDialogHeadingPadding = const EdgeInsets.fromLTRB(24.0, 24.0, 24.0, 20.0);
+/// The radius of a circular material ink response in logical pixels.
+const double kRadialReactionRadius = 24.0;
 
-const double kRadialReactionRadius = 24.0; // Pixels
+/// The amount of time a circular material ink response should take to expand to its full size.
 const Duration kRadialReactionDuration = const Duration(milliseconds: 200);
+
+/// The value of the alpha channel to use when drawing a circular material ink response.
 const int kRadialReactionAlpha = 0x33;

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

@@ -29,6 +29,10 @@ enum _DatePickerMode { day, year }
 ///  * [showDatePicker]
 ///  * <https://www.google.com/design/spec/components/pickers.html#pickers-date-pickers>
 class DatePicker extends StatefulWidget {
+  /// Creates a date picker.
+  ///
+  /// Rather than creating a date picker directly, consider using
+  /// [showDatePicker] to show a date picker in a dialog.
   DatePicker({
     this.selectedDate,
     this.onChanged,
@@ -197,6 +201,9 @@ class _DatePickerHeader extends StatelessWidget {
 ///  * [DatePicker].
 ///  * <https://www.google.com/design/spec/components/pickers.html#pickers-date-pickers>
 class DayPicker extends StatelessWidget {
+  /// Creates a day picker.
+  ///
+  /// Rarely used directly. Instead, typically used as part of a [DatePicker].
   DayPicker({
     this.selectedDate,
     this.currentDate,
@@ -326,6 +333,9 @@ class DayPicker extends StatelessWidget {
 ///  * [DatePicker]
 ///  * <https://www.google.com/design/spec/components/pickers.html#pickers-date-pickers>
 class MonthPicker extends StatefulWidget {
+  /// Creates a month picker.
+  ///
+  /// Rarely used directly. Instead, typically used as part of a [DatePicker].
   MonthPicker({
     Key key,
     this.selectedDate,

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

@@ -80,9 +80,9 @@ class _DatePickerDialogState extends State<_DatePickerDialog> {
 
 /// Shows a dialog containing a material design date picker.
 ///
-/// The returned Future resolves to the date selected by the user when the user
-/// closes the dialog. If the user cancels the dialog, the Future resolves to
-/// the initialDate.
+/// The returned [Future] resolves to the date selected by the user when the
+/// user closes the dialog. If the user cancels the dialog, the [Future]
+/// resolves to the initialDate.
 ///
 /// See also:
 ///

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

@@ -7,6 +7,9 @@ import 'package:flutter/widgets.dart';
 import 'material.dart';
 import 'scaffold.dart';
 
+/// Throws an exception of the given build context is not contained in a [Material] widget.
+///
+/// Does nothing if asserts are disabled.
 bool debugCheckHasMaterial(BuildContext context) {
   assert(() {
     if (context.widget is! Material && context.ancestorWidgetOfExactType(Material) == null) {
@@ -30,7 +33,9 @@ bool debugCheckHasMaterial(BuildContext context) {
   return true;
 }
 
-
+/// Throws an exception of the given build context is not contained in a [Scaffold] widget.
+///
+/// Does nothing if asserts are disabled.
 bool debugCheckHasScaffold(BuildContext context) {
   assert(() {
     if (Scaffold.of(context) == null) {

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

@@ -11,12 +11,18 @@ import 'colors.dart';
 import 'material.dart';
 import 'theme.dart';
 
-typedef Widget DialogBuilder(NavigatorState navigator);
-
 /// A material design dialog
 ///
-/// <https://www.google.com/design/spec/components/dialogs.html>
+/// Typically passed as the child widget to [showDialog], which displays the
+/// dialog.
+///
+/// See also:
+///  * [showDialog]
+///  * <https://www.google.com/design/spec/components/dialogs.html>
 class Dialog extends StatelessWidget {
+  /// Creates a dialog.
+  ///
+  /// Typically used in conjunction with [showDialog].
   Dialog({
     Key key,
     this.title,
@@ -56,7 +62,6 @@ class Dialog extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-
     List<Widget> dialogBody = new List<Widget>();
 
     if (title != null) {
@@ -150,6 +155,17 @@ class _DialogRoute<T> extends PopupRoute<T> {
   }
 }
 
+/// Displays a dialog above the current contents of the app.
+///
+/// This function typically receives a [Dialog] widget as its child argument.
+/// Content below the dialog is dimmed with a [ModalBarrier].
+///
+/// Returns a `Future` that resolves to the value (if any) that was passed to
+/// [Navigator.pop] when the dialog was closed.
+///
+/// See also:
+///  * [Dialog]
+///  * <https://www.google.com/design/spec/components/dialogs.html>
 Future<dynamic/*=T*/> showDialog/*<T>*/({ BuildContext context, Widget child }) {
   Completer<dynamic/*=T*/> completer = new Completer<dynamic/*=T*/>();
   Navigator.push(context, new _DialogRoute<dynamic/*=T*/>(completer: completer, child: child));

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

@@ -6,13 +6,42 @@ import 'package:flutter/widgets.dart';
 
 import 'theme.dart';
 
+/// A material design divider.
+///
+/// A one logical pixel thick horizontal line.
+///
+/// Dividers can be used in lists and [Drawer]s to separate content vertically.
+/// To create a one-pixel divider between items in a list, consider using
+/// [ListItem.divideItems], which is optimized for this case.
+///
+/// See also:
+///  * [ListItem.divideItems]
+///  * <https://www.google.com/design/spec/components/dividers.html>
 class Divider extends StatelessWidget {
-  Divider({ Key key, this.height: 16.0, this.indent: 0.0, this.color }) : super(key: key) {
+  /// Creates a material design divider.
+  ///
+  /// The height must be at least 1.0 logical pixels.
+  Divider({
+    Key key,
+    this.height: 16.0,
+    this.indent: 0.0,
+    this.color
+  }) : super(key: key) {
     assert(height >= 1.0);
   }
 
+  /// The divider's vertical extent.
+  ///
+  /// The divider itself is always drawn as one logical pixel thick horizontal
+  /// line that is centered within the height specified by this value.
   final double height;
+
+  /// The amount of empty space to the left of the divider.
   final double indent;
+
+  /// The color to use when painting the line.
+  ///
+  /// Defaults to [ThemeData.dividerColor].
   final Color color;
 
   @override

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

@@ -42,6 +42,9 @@ const Duration _kBaseSettleDuration = const Duration(milliseconds: 246);
 ///  * [DrawerHeader]
 ///  * <https://www.google.com/design/spec/patterns/navigation-drawer.html>
 class Drawer extends StatelessWidget {
+  /// Creates a material design drawer.
+  ///
+  /// Typically used in the [Scaffold.drawer] property.
   Drawer({
     Key key,
     this.elevation: 16,
@@ -83,6 +86,7 @@ class DrawerController extends StatefulWidget {
     this.child
   }) : super(key: key);
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override

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

@@ -4,10 +4,11 @@
 
 import 'package:flutter/widgets.dart';
 
-import 'constants.dart';
 import 'debug.dart';
 import 'theme.dart';
 
+const double _kDrawerHeaderHeight = 140.0;
+
 /// The top-most region of a material design drawer.
 ///
 /// Part of the material design [Drawer].
@@ -20,6 +21,9 @@ import 'theme.dart';
 ///  * [DrawerItem]
 ///  * <https://www.google.com/design/spec/patterns/navigation-drawer.html>
 class DrawerHeader extends StatelessWidget {
+  /// Creates a material design drawer header.
+  ///
+  /// Requires one of its ancestors to be a [Material] widget.
   const DrawerHeader({ Key key, this.child }) : super(key: key);
 
   /// The widget below this widget in the tree.
@@ -30,7 +34,7 @@ class DrawerHeader extends StatelessWidget {
     assert(debugCheckHasMaterial(context));
     final double statusBarHeight = MediaQuery.of(context).padding.top;
     return new Container(
-      height: statusBarHeight + kMaterialDrawerHeight,
+      height: statusBarHeight + _kDrawerHeaderHeight,
       decoration: new BoxDecoration(
         // TODO(jackson): This class should usually render the user's
         // preferred banner image rather than a solid background

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

@@ -23,6 +23,9 @@ import 'theme.dart';
 ///  * [DrawerHeader]
 ///  * <https://www.google.com/design/spec/patterns/navigation-drawer.html>
 class DrawerItem extends StatelessWidget {
+  /// Creates a material design drawer item.
+  ///
+  /// Requires one of its ancestors to be a [Material] widget.
   const DrawerItem({
     Key key,
     this.icon,

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

@@ -4,7 +4,6 @@
 
 import 'package:flutter/widgets.dart';
 
-import 'constants.dart';
 import 'overscroll_painter.dart';
 import 'theme.dart';
 
@@ -16,10 +15,10 @@ enum MaterialListType {
 }
 
 Map<MaterialListType, double> kListItemExtent = const <MaterialListType, double>{
-  MaterialListType.oneLine: kOneLineListItemHeight,
-  MaterialListType.oneLineWithAvatar: kOneLineListItemWithAvatarHeight,
-  MaterialListType.twoLine: kTwoLineListItemHeight,
-  MaterialListType.threeLine: kThreeLineListItemHeight,
+  MaterialListType.oneLine: 48.0,
+  MaterialListType.oneLineWithAvatar: 56.0,
+  MaterialListType.twoLine: 72.0,
+  MaterialListType.threeLine: 88.0,
 };
 
 class MaterialList extends StatefulWidget {

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

@@ -35,6 +35,16 @@ const double _kInnerRadius = 5.0;
 ///  * [Switch]
 ///  * <https://www.google.com/design/spec/components/selection-controls.html#selection-controls-radio-button>
 class Radio<T> extends StatelessWidget {
+  /// Creates a material design radio button.
+  ///
+  /// The radio button itself does not maintain any state. Instead, when the state
+  /// of the radio button changes, the widget calls the [onChanged] callback.
+  /// Most widget that use a radio button will listen for the [onChanged]
+  /// callback and rebuild the radio button with a new [groupValue] to update the
+  /// visual appearance of the radio button.
+  ///
+  /// * [value] and [groupValue] together determines whether the radio button is selected.
+  /// * [onChanged] is when the user selects this radio button.
   Radio({
     Key key,
     this.value,

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

@@ -39,6 +39,15 @@ import 'typography.dart';
 ///  * [Switch]
 ///  * <https://www.google.com/design/spec/components/sliders.html>
 class Slider extends StatelessWidget {
+  /// Creates a material design slider.
+  ///
+  /// The slider itself does not maintain any state. Instead, when the state of
+  /// the slider changes, the widget calls the [onChanged] callback. Most widgets
+  /// that use a slider will listen for the [onChanged] callback and rebuild the
+  /// slider with a new [value] to update the visual appearance of the slider.
+  ///
+  /// * [value] determines currently selected value for this slider.
+  /// * [onChanged] is called when the user selects a new value for the slider.
   Slider({
     Key key,
     this.value,

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

@@ -31,6 +31,15 @@ import 'toggleable.dart';
 ///  * [Slider]
 ///  * <https://www.google.com/design/spec/components/selection-controls.html#selection-controls-switch>
 class Switch extends StatelessWidget {
+  /// Creates a material design switch.
+  ///
+  /// The switch itself does not maintain any state. Instead, when the state of
+  /// the switch changes, the widget calls the [onChanged] callback. Most widgets
+  /// that use a switch will listen for the [onChanged] callback and rebuild the
+  /// switch with a new [value] to update the visual appearance of the switch.
+  ///
+  /// * [value] determines this switch is on or off.
+  /// * [onChanged] is called when the user toggles with switch on or off.
   Switch({
     Key key,
     this.value,

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

@@ -10,7 +10,6 @@ import 'package:flutter/widgets.dart';
 import 'colors.dart';
 import 'theme.dart';
 import 'typography.dart';
-import 'constants.dart';
 
 const Duration _kDialAnimateDuration = const Duration(milliseconds: 200);
 const double _kTwoPi = 2 * math.PI;
@@ -18,8 +17,12 @@ const int _kHoursPerDay = 24;
 const int _kHoursPerPeriod = 12;
 const int _kMinutesPerHour = 60;
 
+/// Whether the [TimeOfDay] is before or after noon.
 enum DayPeriod {
+  /// Ante meridiem (before noon).
   am,
+
+  /// Post meridiem (after noon).
   pm,
 }
 
@@ -217,7 +220,7 @@ class _TimePickerHeader extends StatelessWidget {
     );
 
     return new Container(
-      padding: kDialogHeadingPadding,
+      padding: const EdgeInsets.fromLTRB(24.0, 24.0, 24.0, 20.0),
       decoration: new BoxDecoration(backgroundColor: theme.primaryColor),
       child: new Row(
         children: <Widget>[