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/colors.dart

@@ -9,21 +9,53 @@ import 'dart:ui' show Color;
 class Colors {
   Colors._();
 
+  /// Completely invisible.
   static const Color transparent = const Color(0x00000000);
 
+  /// Completely opaque black.
   static const Color black   = const Color(0xFF000000);
+
+  /// Black with 87% opacity.
   static const Color black87 = const Color(0xDD000000);
+
+  /// Black with 54% opacity.
   static const Color black54 = const Color(0x8A000000);
-  static const Color black45 = const Color(0x73000000); // mask color
-  static const Color black26 = const Color(0x42000000); // disabled radio buttons and text of disabled flat buttons in light theme
-  static const Color black12 = const Color(0x1F000000); // background of disabled raised buttons in light theme
 
+  /// Black with 45% opacity.
+  ///
+  /// Used for modal barriers.
+  static const Color black45 = const Color(0x73000000);
+
+  /// Black with 26% opacity.
+  ///
+  /// Used for disabled radio buttons and text of disabled flat buttons in the light theme.
+  static const Color black26 = const Color(0x42000000);
+
+  /// Black with 12% opacity.
+  ///
+  /// Used for the background of disabled raised buttons in the light theme.
+  static const Color black12 = const Color(0x1F000000);
+
+  /// Completely opaque white.
   static const Color white   = const Color(0xFFFFFFFF);
+
+  /// White with 70% opacity.
   static const Color white70 = const Color(0xB3FFFFFF);
-  static const Color white30 = const Color(0x4DFFFFFF); // disabled radio buttons and text of disabled flat buttons in dark theme
-  static const Color white12 = const Color(0x1FFFFFFF); // background of disabled raised buttons in dark theme
+
+  /// White with 32% opacity.
+  ///
+  /// Used for disabled radio buttons and text of disabled flat buttons in the dark theme.
+  static const Color white30 = const Color(0x4DFFFFFF);
+
+  /// White with 12% opacity.
+  ///
+  /// Used for the background of disabled raised buttons in the dark theme.
+  static const Color white12 = const Color(0x1FFFFFFF);
+
+  /// White with 10% opacity.
   static const Color white10 = const Color(0x1AFFFFFF);
 
+  /// The red primary swatch.
   static const Map<int, Color> red = const <int, Color>{
      50: const Color(0xFFFFEBEE),
     100: const Color(0xFFFFCDD2),
@@ -37,6 +69,7 @@ class Colors {
     900: const Color(0xFFB71C1C),
   };
 
+  /// The red accent swatch.
   static const Map<int, Color> redAccent = const <int, Color>{
     100: const Color(0xFFFF8A80),
     200: const Color(0xFFFF5252),
@@ -44,6 +77,7 @@ class Colors {
     700: const Color(0xFFD50000),
   };
 
+  /// The pink primary swatch.
   static const Map<int, Color> pink = const <int, Color>{
      50: const Color(0xFFFCE4EC),
     100: const Color(0xFFF8BBD0),
@@ -57,6 +91,7 @@ class Colors {
     900: const Color(0xFF880E4F),
   };
 
+  /// The pink accent swatch.
   static const Map<int, Color> pinkAccent = const <int, Color>{
     100: const Color(0xFFFF80AB),
     200: const Color(0xFFFF4081),
@@ -64,6 +99,7 @@ class Colors {
     700: const Color(0xFFC51162),
   };
 
+  /// The purple primary swatch.
   static const Map<int, Color> purple = const <int, Color>{
      50: const Color(0xFFF3E5F5),
     100: const Color(0xFFE1BEE7),
@@ -77,6 +113,7 @@ class Colors {
     900: const Color(0xFF4A148C),
   };
 
+  /// The purple accent swatch.
   static const Map<int, Color> purpleAccent = const <int, Color>{
     100: const Color(0xFFEA80FC),
     200: const Color(0xFFE040FB),
@@ -84,6 +121,7 @@ class Colors {
     700: const Color(0xFFAA00FF),
   };
 
+  /// The deep purple primary swatch.
   static const Map<int, Color> deepPurple = const <int, Color>{
      50: const Color(0xFFEDE7F6),
     100: const Color(0xFFD1C4E9),
@@ -97,6 +135,7 @@ class Colors {
     900: const Color(0xFF311B92),
   };
 
+  /// The deep purple accent swatch.
   static const Map<int, Color> deepPurpleAccent = const <int, Color>{
     100: const Color(0xFFB388FF),
     200: const Color(0xFF7C4DFF),
@@ -104,6 +143,7 @@ class Colors {
     700: const Color(0xFF6200EA),
   };
 
+  /// The indigo primary swatch.
   static const Map<int, Color> indigo = const <int, Color>{
      50: const Color(0xFFE8EAF6),
     100: const Color(0xFFC5CAE9),
@@ -117,6 +157,7 @@ class Colors {
     900: const Color(0xFF1A237E),
   };
 
+  /// The indigo accent swatch.
   static const Map<int, Color> indigoAccent = const <int, Color>{
     100: const Color(0xFF8C9EFF),
     200: const Color(0xFF536DFE),
@@ -124,6 +165,7 @@ class Colors {
     700: const Color(0xFF304FFE),
   };
 
+  /// The blue primary swatch.
   static const Map<int, Color> blue = const <int, Color>{
      50: const Color(0xFFE3F2FD),
     100: const Color(0xFFBBDEFB),
@@ -137,6 +179,7 @@ class Colors {
     900: const Color(0xFF0D47A1),
   };
 
+  /// The blue accent swatch.
   static const Map<int, Color> blueAccent = const <int, Color>{
     100: const Color(0xFF82B1FF),
     200: const Color(0xFF448AFF),
@@ -144,6 +187,7 @@ class Colors {
     700: const Color(0xFF2962FF),
   };
 
+  /// The light blue primary swatch.
   static const Map<int, Color> lightBlue = const <int, Color>{
      50: const Color(0xFFE1F5FE),
     100: const Color(0xFFB3E5FC),
@@ -157,6 +201,7 @@ class Colors {
     900: const Color(0xFF01579B),
   };
 
+  /// The light blue accent swatch.
   static const Map<int, Color> lightBlueAccent = const <int, Color>{
     100: const Color(0xFF80D8FF),
     200: const Color(0xFF40C4FF),
@@ -164,6 +209,7 @@ class Colors {
     700: const Color(0xFF0091EA),
   };
 
+  /// The cyan primary swatch.
   static const Map<int, Color> cyan = const <int, Color>{
      50: const Color(0xFFE0F7FA),
     100: const Color(0xFFB2EBF2),
@@ -177,6 +223,7 @@ class Colors {
     900: const Color(0xFF006064),
   };
 
+  /// The cyan accent swatch.
   static const Map<int, Color> cyanAccent = const <int, Color>{
     100: const Color(0xFF84FFFF),
     200: const Color(0xFF18FFFF),
@@ -184,6 +231,7 @@ class Colors {
     700: const Color(0xFF00B8D4),
   };
 
+  /// The teal primary swatch.
   static const Map<int, Color> teal = const <int, Color>{
      50: const Color(0xFFE0F2F1),
     100: const Color(0xFFB2DFDB),
@@ -197,6 +245,7 @@ class Colors {
     900: const Color(0xFF004D40),
   };
 
+  /// The teal accent swatch.
   static const Map<int, Color> tealAccent = const <int, Color>{
     100: const Color(0xFFA7FFEB),
     200: const Color(0xFF64FFDA),
@@ -204,6 +253,7 @@ class Colors {
     700: const Color(0xFF00BFA5),
   };
 
+  /// The green primary swatch.
   static const Map<int, Color> green = const <int, Color>{
      50: const Color(0xFFE8F5E9),
     100: const Color(0xFFC8E6C9),
@@ -217,6 +267,7 @@ class Colors {
     900: const Color(0xFF1B5E20),
   };
 
+  /// The green accent swatch.
   static const Map<int, Color> greenAccent = const <int, Color>{
     100: const Color(0xFFB9F6CA),
     200: const Color(0xFF69F0AE),
@@ -224,6 +275,7 @@ class Colors {
     700: const Color(0xFF00C853),
   };
 
+  /// The light green primary swatch.
   static const Map<int, Color> lightGreen = const <int, Color>{
      50: const Color(0xFFF1F8E9),
     100: const Color(0xFFDCEDC8),
@@ -237,6 +289,7 @@ class Colors {
     900: const Color(0xFF33691E),
   };
 
+  /// The light green accent swatch.
   static const Map<int, Color> lightGreenAccent = const <int, Color>{
     100: const Color(0xFFCCFF90),
     200: const Color(0xFFB2FF59),
@@ -244,6 +297,7 @@ class Colors {
     700: const Color(0xFF64DD17),
   };
 
+  /// The lime primary swatch.
   static const Map<int, Color> lime = const <int, Color>{
      50: const Color(0xFFF9FBE7),
     100: const Color(0xFFF0F4C3),
@@ -257,6 +311,7 @@ class Colors {
     900: const Color(0xFF827717),
   };
 
+  /// The lime accent primary swatch.
   static const Map<int, Color> limeAccent = const <int, Color>{
     100: const Color(0xFFF4FF81),
     200: const Color(0xFFEEFF41),
@@ -264,6 +319,7 @@ class Colors {
     700: const Color(0xFFAEEA00),
   };
 
+  /// The yellow primary swatch.
   static const Map<int, Color> yellow = const <int, Color>{
      50: const Color(0xFFFFFDE7),
     100: const Color(0xFFFFF9C4),
@@ -277,6 +333,7 @@ class Colors {
     900: const Color(0xFFF57F17),
   };
 
+  /// The yellow accent swatch.
   static const Map<int, Color> yellowAccent = const <int, Color>{
     100: const Color(0xFFFFFF8D),
     200: const Color(0xFFFFFF00),
@@ -284,6 +341,7 @@ class Colors {
     700: const Color(0xFFFFD600),
   };
 
+  /// The amber primary swatch.
   static const Map<int, Color> amber = const <int, Color>{
      50: const Color(0xFFFFF8E1),
     100: const Color(0xFFFFECB3),
@@ -297,6 +355,7 @@ class Colors {
     900: const Color(0xFFFF6F00),
   };
 
+  /// The amber accent swatch.
   static const Map<int, Color> amberAccent = const <int, Color>{
     100: const Color(0xFFFFE57F),
     200: const Color(0xFFFFD740),
@@ -304,6 +363,7 @@ class Colors {
     700: const Color(0xFFFFAB00),
   };
 
+  /// The orange primary swatch.
   static const Map<int, Color> orange = const <int, Color>{
      50: const Color(0xFFFFF3E0),
     100: const Color(0xFFFFE0B2),
@@ -317,6 +377,7 @@ class Colors {
     900: const Color(0xFFE65100),
   };
 
+  /// The orange accent swatch.
   static const Map<int, Color> orangeAccent = const <int, Color>{
     100: const Color(0xFFFFD180),
     200: const Color(0xFFFFAB40),
@@ -324,6 +385,7 @@ class Colors {
     700: const Color(0xFFFF6D00),
   };
 
+  /// The deep orange primary swatch.
   static const Map<int, Color> deepOrange = const <int, Color>{
      50: const Color(0xFFFBE9E7),
     100: const Color(0xFFFFCCBC),
@@ -337,6 +399,7 @@ class Colors {
     900: const Color(0xFFBF360C),
   };
 
+  /// The deep orange accent swatch.
   static const Map<int, Color> deepOrangeAccent = const <int, Color>{
     100: const Color(0xFFFF9E80),
     200: const Color(0xFFFF6E40),
@@ -344,6 +407,7 @@ class Colors {
     700: const Color(0xFFDD2C00),
   };
 
+  /// The brown primary swatch.
   static const Map<int, Color> brown = const <int, Color>{
      50: const Color(0xFFEFEBE9),
     100: const Color(0xFFD7CCC8),
@@ -357,6 +421,7 @@ class Colors {
     900: const Color(0xFF3E2723),
   };
 
+  /// The grey primary swatch.
   static const Map<int, Color> grey = const <int, Color>{
      50: const Color(0xFFFAFAFA),
     100: const Color(0xFFF5F5F5),
@@ -372,6 +437,7 @@ class Colors {
     900: const Color(0xFF212121),
   };
 
+  /// The blue-grey primary swatch.
   static const Map<int, Color> blueGrey = const <int, Color>{
      50: const Color(0xFFECEFF1),
     100: const Color(0xFFCFD8DC),
@@ -385,7 +451,7 @@ class Colors {
     900: const Color(0xFF263238),
   };
 
-  /// All Material design primary color swatches (except grey)
+  /// The material design primary color swatches (except grey).
   static const List<Map<int, Color>> primaries = const <Map<int, Color>>[
     red,
     pink,
@@ -408,7 +474,7 @@ class Colors {
     blueGrey,
   ];
 
-  /// All Material design accent color swatches
+  /// The material design accent color swatches.
   static const List<Map<int, Color>> accents = const <Map<int, Color>>[
     redAccent,
     pinkAccent,

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>[