Add more dartdoc to material.dart (#3702)

This patch completes the circuit on this library. The next step is to go
through and add docs to anything we missed.

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

@@ -18,6 +18,7 @@ import 'theme.dart';
 /// See also:
 ///
 ///  * [ListItem.divideItems]
+///  * [PopupMenuDivider]
 ///  * <https://www.google.com/design/spec/components/dividers.html>
 class Divider extends StatelessWidget {
   /// Creates a material design divider.

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

@@ -91,11 +91,25 @@ class _Painter extends CustomPainter {
 /// If the OverscrollIndicator's child has more than one Scrollable descendant
 /// the scrollableKey parameter can be used to identify the one to track.
 class OverscrollIndicator extends StatefulWidget {
-  OverscrollIndicator({ Key key, this.scrollableKey, this.child }) : super(key: key) {
+  /// Creates an overscroll indicator.
+  ///
+  /// The [child] argument must not be null.
+  OverscrollIndicator({
+    Key key,
+    this.scrollableKey,
+    this.child
+  }) : super(key: key) {
     assert(child != null);
   }
 
+  /// Identifies the [Scrollable] descendant of child that the overscroll
+  /// indicator will track. Can be null if there's only one [Scrollable]
+  /// descendant.
   final Key scrollableKey;
+
+  /// The overscroll indicator will be stacked on top of this child. The
+  /// indicator will appear when child's [Scrollable] descendant is
+  /// over-scrolled.
   final Widget child;
 
   @override

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

@@ -39,9 +39,15 @@ class _MaterialPageTransition extends AnimatedWidget {
   }
 }
 
-const Duration kMaterialPageRouteTransitionDuration = const Duration(milliseconds: 150);
-
+/// A modal route that replaces the entire screen with a material design transition.
+///
+/// The entrance transition for the page slides the page upwards and fades it
+/// in. The exit transition is the same, but in reverse.
+///
+/// [MaterialApp] creates material page routes for entries in the
+/// [MaterialApp.routes] map.
 class MaterialPageRoute<T> extends PageRoute<T> {
+  /// Creates a page route for use in a material design app.
   MaterialPageRoute({
     this.builder,
     Completer<T> completer,
@@ -51,10 +57,11 @@ class MaterialPageRoute<T> extends PageRoute<T> {
     assert(opaque);
   }
 
+  /// Builds the primary contents of the route.
   final WidgetBuilder builder;
 
   @override
-  Duration get transitionDuration => kMaterialPageRouteTransitionDuration;
+  Duration get transitionDuration => const Duration(milliseconds: 150);
 
   @override
   Color get barrierColor => null;

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

@@ -29,20 +29,60 @@ const double _kMenuVerticalPadding = 8.0;
 const double _kMenuWidthStep = 56.0;
 const double _kMenuScreenPadding = 8.0;
 
+/// A base class for entries in a material design popup menu.
+///
+/// The popup menu widget uses this interface to interact with the menu items.
+/// To show a popup menu, use the [showMenu] function. To create a button that
+/// shows a popup menu, consider using [PopupMenuButton].
+///
+/// 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.
+///
+/// See also:
+///
+///  * [PopupMenuItem]
+///  * [PopupMenuDivider]
+///  * [CheckedPopupMenuItem]
+///  * [showMenu]
+///  * [PopupMenuButton]
 abstract class PopupMenuEntry<T> extends StatefulWidget {
-  PopupMenuEntry({ Key key }) : super(key: key);
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
+  const PopupMenuEntry({ Key key }) : super(key: key);
 
+  /// The amount of vertical space occupied by this entry.
+  ///
+  /// This value must remain constant for a given instance.
   double get height;
+
+  /// The value that should be returned by [showMenu] when the user selects this entry.
   T get value => null;
-  bool get enabled => true;
+
+  /// Whether the user is permitted to select this entry.
+  bool get enabled;
 }
 
+/// A horizontal divider in a material design popup menu.
+///
+/// This widget adatps the [Divider] for use in popup menus.
+///
+/// See also:
+///
+///  * [PopupMenuItem]
+///  * [showMenu]
+///  * [PopupMenuButton]
 class PopupMenuDivider extends PopupMenuEntry<dynamic> {
+  /// Creates a horizontal divider for a popup menu.
+  ///
+  /// By default, the divider has a height of 16.0 logical pixels.
   PopupMenuDivider({ Key key, this.height: 16.0 }) : super(key: key);
 
   @override
   final double height;
 
+  @override
+  bool get enabled => false;
+
   @override
   _PopupMenuDividerState createState() => new _PopupMenuDividerState();
 }
@@ -52,7 +92,24 @@ class _PopupMenuDividerState extends State<PopupMenuDivider> {
   Widget build(BuildContext context) => new Divider(height: config.height);
 }
 
+/// An item in a material design popup menu.
+///
+/// To show a popup menu, use the [showMenu] function. To create a button that
+/// shows a popup menu, consider using [PopupMenuButton].
+///
+/// To show a checkmark next to a popup menu item, consider using
+/// [CheckedPopupMenuItem].
+///
+/// See also:
+///
+///  * [PopupMenuDivider]
+///  * [CheckedPopupMenuItem]
+///  * [showMenu]
+///  * [PopupMenuButton]
 class PopupMenuItem<T> extends PopupMenuEntry<T> {
+  /// Creates an item for a popup menu.
+  ///
+  /// By default, the item is enabled.
   PopupMenuItem({
     Key key,
     this.value,
@@ -121,7 +178,22 @@ class _PopupMenuItemState<T extends PopupMenuItem<dynamic>> extends State<T> {
   }
 }
 
+/// An item with a checkmark in a material design popup menu.
+///
+/// To show a popup menu, use the [showMenu] function. To create a button that
+/// shows a popup menu, consider using [PopupMenuButton].
+///
+/// See also:
+///
+///  * [PopupMenuItem]
+///  * [PopupMenuDivider]
+///  * [CheckedPopupMenuItem]
+///  * [showMenu]
+///  * [PopupMenuButton]
 class CheckedPopupMenuItem<T> extends PopupMenuItem<T> {
+  /// Creates a popup menu item with a checkmark.
+  ///
+  /// By default, the menu item is enabled but unchecked.
   CheckedPopupMenuItem({
     Key key,
     T value,
@@ -135,6 +207,7 @@ class CheckedPopupMenuItem<T> extends PopupMenuItem<T> {
     child: child
   );
 
+  /// Whether to display a checkmark next to the menu item.
   final bool checked;
 
   @override
@@ -407,8 +480,10 @@ class PopupMenuButton<T> extends StatefulWidget {
   /// Called when the button is pressed to create the items to show in the menu.
   final PopupMenuItemBuilder<T> itemBuilder;
 
+  /// The value of the menu item, if any, that should be highlighted when the menu opens.
   final T initialValue;
 
+  /// Called when the user selects a value from the popup menu created by this button.
   final PopupMenuItemSelected<T> onSelected;
 
   /// Text that describes the action that will occur when the button is pressed.

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

@@ -52,6 +52,10 @@ enum RefreshIndicatorLocation { top, bottom }
 ///
 ///  * <https://www.google.com/design/spec/patterns/swipe-to-refresh.html>
 class RefreshIndicator extends StatefulWidget {
+  /// Creates a refresh indicator.
+  ///
+  /// The [refresh] and [child] arguments must be non-null. The default
+  /// [displacement] is 40.0 logical pixels.
   RefreshIndicator({
     Key key,
     this.scrollableKey,
@@ -65,7 +69,7 @@ class RefreshIndicator extends StatefulWidget {
 
   /// Identifies the [Scrollable] descendant of child that will cause the
   /// refresh indicator to appear. Can be null if there's only one
-  /// Scrollable descendant.
+  /// [Scrollable] descendant.
   final Key scrollableKey;
 
   /// The distance from the child's top or bottom edge to where the refresh indicator
@@ -73,7 +77,6 @@ class RefreshIndicator extends StatefulWidget {
   /// displacement may significantly exceed this value.
   final double displacement;
 
-
   /// A function that's called when the user has dragged the refresh indicator
   /// far enough to demonstrate that they want the app to refresh. The returned
   /// Future must complete when the refresh operation is finished.

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

@@ -76,11 +76,19 @@ class _Painter extends CustomPainter {
 /// the scrollableKey parameter can be used to identify the one the Scrollbar
 /// should track.
 class Scrollbar extends StatefulWidget {
+  /// Creates a scrollbar.
+  ///
+  /// The child argument must not be null.
   Scrollbar({ Key key, this.scrollableKey, this.child }) : super(key: key) {
     assert(child != null);
   }
 
+  /// Identifies the [Scrollable] descendant of child that the scrollbar will
+  /// track. Can be null if there's only one [Scrollable] descendant.
   final Key scrollableKey;
+
+  /// The scrollbar will be stacked on top of this child. The scrollbar will
+  /// display when child's [Scrollable] descendant is scrolled.
   final Widget child;
 
   @override
@@ -167,4 +175,4 @@ class _ScrollbarState extends State<Scrollbar> {
       )
     );
   }
-}
\ No newline at end of file
+}

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

@@ -43,6 +43,9 @@ const Curve _snackBarFadeCurve = const Interval(0.72, 1.0, curve: Curves.fastOut
 ///  * [SnackBar]
 ///  * <https://www.google.com/design/spec/components/snackbars-toasts.html>
 class SnackBarAction extends StatefulWidget {
+  /// Creates an action for a [SnackBar].
+  ///
+  /// The [label] and [onPressed] arguments must be non-null.
   SnackBarAction({Key key, this.label, this.onPressed }) : super(key: key) {
     assert(label != null);
     assert(onPressed != null);
@@ -97,6 +100,9 @@ class _SnackBarActionState extends State<SnackBarAction> {
 ///  * [SnackBarAction]
 ///  * <https://www.google.com/design/spec/components/snackbars-toasts.html>
 class SnackBar extends StatelessWidget {
+  /// Creates a snack bar.
+  ///
+  /// The [content] argument must be non-null.
   SnackBar({
     Key key,
     this.content,
@@ -107,9 +113,21 @@ class SnackBar extends StatelessWidget {
     assert(content != null);
   }
 
+  /// The primary content of the snack bar.
+  ///
+  /// Typically a [Text] widget.
   final Widget content;
+
+  /// (optional) An action that the user can take based on the snack bar.
+  ///
+  /// For example, the snack bar might let the user undo the operation that
+  /// prompted the snackbar. Snack bars can have at most one action.
   final SnackBarAction action;
+
+  /// The amount of time the snack bar should be displayed.
   final Duration duration;
+
+  /// The animation driving the entrance and exit of the snack bar.
   final Animation<double> animation;
 
   @override
@@ -180,6 +198,7 @@ class SnackBar extends StatelessWidget {
 
   // API for Scaffold.addSnackBar():
 
+  /// Creates an animation controller useful for driving a snack bar's entrance and exit animation.
   static AnimationController createAnimationController() {
     return new AnimationController(
       duration: _kSnackBarTransitionDuration,
@@ -187,6 +206,10 @@ class SnackBar extends StatelessWidget {
     );
   }
 
+  /// Creates a copy of this snack bar but with the animation replaced with the given animation.
+  ///
+  /// If the original snack bar lacks a key, the newly created snack bar will
+  /// use the given fallback key.
   SnackBar withAnimation(Animation<double> newAnimation, { Key fallbackKey }) {
     return new SnackBar(
       key: key ?? fallbackKey,

packages/flutter/test/widget/page_forward_transitions_test.dart

@@ -34,7 +34,7 @@ class TestRoute<T> extends PageRoute<T> {
   final Widget child;
 
   @override
-  Duration get transitionDuration => kMaterialPageRouteTransitionDuration;
+  Duration get transitionDuration => const Duration(milliseconds: 150);
 
   @override
   Color get barrierColor => null;
@@ -46,8 +46,8 @@ class TestRoute<T> extends PageRoute<T> {
 }
 
 void main() {
-  final Duration kTwoTenthsOfTheTransitionDuration = kMaterialPageRouteTransitionDuration * 0.2;
-  final Duration kFourTenthsOfTheTransitionDuration = kMaterialPageRouteTransitionDuration * 0.4;
+  final Duration kTwoTenthsOfTheTransitionDuration = const Duration(milliseconds: 30);
+  final Duration kFourTenthsOfTheTransitionDuration = const Duration(milliseconds: 60);
 
   testWidgets('Check onstage/offstage handling around transitions', (WidgetTester tester) {