Add more dartdoc to material.dart (#3167)

Also, clean up a few interfaces that looked awkward when writing docs.

dev/manual_tests/card_collection.dart

@@ -282,16 +282,14 @@ class CardCollectionState extends State<CardCollection> {
       actions: <Widget>[
         new Text(_dismissDirectionText(_dismissDirection))
       ],
-      flexibleSpace: (_) {
+      flexibleSpace: new Container(
-        return new Container(
+        padding: const EdgeInsets.only(left: 72.0),
-          padding: const EdgeInsets.only(left: 72.0),
+        height: 128.0,
-          height: 128.0,
+        child: new Align(
-          child: new Align(
+          alignment: const FractionalOffset(0.0, 0.75),
-            alignment: const FractionalOffset(0.0, 0.75),
+          child: new Text('Swipe Away: ${_cardModels.length}', style: Theme.of(context).primaryTextTheme.title)
-            child: new Text('Swipe Away: ${_cardModels.length}', style: Theme.of(context).primaryTextTheme.title)
+        )
-          )
+      )
-        );
-      }
     );
   }
 

examples/material_gallery/lib/demo/flexible_space_demo.dart

@@ -122,16 +122,14 @@ class FlexibleSpaceDemoState extends State<FlexibleSpaceDemo> {
               ]
             )
           ],
-          flexibleSpace: (BuildContext context) {
+          flexibleSpace: new FlexibleSpaceBar(
-            return new FlexibleSpaceBar(
+            title : new Text('Ali Connors'),
-              title : new Text('Ali Connors'),
+            image: new AssetImage(
-              image: new AssetImage(
+              name: 'packages/flutter_gallery_assets/ali_connors.png',
-                name: 'packages/flutter_gallery_assets/ali_connors.png',
+              fit: ImageFit.cover,
-                fit: ImageFit.cover,
+              height: _appBarHeight
-                height: _appBarHeight
+            )
-              )
+          )
-            );
-          }
         ),
         body: new Block(
           scrollableKey: _scrollableKey,

examples/material_gallery/lib/gallery/home.dart

@@ -83,7 +83,7 @@ class GalleryHomeState extends State<GalleryHome> {
       ),
       appBar: new AppBar(
         expandedHeight: _kFlexibleSpaceMaxHeight,
-        flexibleSpace: (BuildContext context) =>  new FlexibleSpaceBar(
+        flexibleSpace: new FlexibleSpaceBar(
           image: new GalleryHeader(),
           title: new Text("Flutter gallery")
         )

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

@@ -22,7 +22,19 @@ const TextStyle _errorTextStyle = const TextStyle(
   decorationStyle: TextDecorationStyle.double
 );
 
-
+/// An application that uses material design.
+///
+/// A convenience widget that wraps a number of widgets that are commonly
+/// required for material design applications. It builds upon
+/// [WidgetsApp] by adding material-design specific functionality, such as
+/// [AnimatedTheme] and [GridPaper]. This widget also configures the top-level
+/// [Navigator] to perform [Hero] animations.
+///
+/// See also:
+///
+///  * [WidgetsApp]
+///  * [Scaffold]
+///  * [MaterialPageRoute]
 class MaterialApp extends WidgetsApp {
   MaterialApp({
     Key key,
@@ -65,6 +77,12 @@ class MaterialApp extends WidgetsApp {
   /// The colors to use for the application's widgets.
   final ThemeData theme;
 
+  /// The application's top-level routing table.
+  ///
+  /// When a named route is pushed with [Navigator.pushNamed], the route name is
+  /// looked up in this map. If the name is present, the associated
+  /// [WidgetBuilder] is used to construct a [MaterialPageRoute] that performs
+  /// an appropriate transition, including [Hero] animations, to the new route.
   final Map<String, WidgetBuilder> routes;
 
   /// Turns on a [GridPaper] overlay that paints a baseline grid

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

@@ -12,6 +12,24 @@ import 'tabs.dart';
 import 'theme.dart';
 import 'typography.dart';
 
+/// A material design app bar.
+///
+/// An app bar consists of a tool bar and potentially other widgets, such as a
+/// [TabBar] and a [FlexibleSpaceBar]. App bars typically expose one or more
+/// 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.
+///
+/// See also:
+///
+///  * [Scaffold]
+///  * [TabBar]
+///  * [IconButton]
+///  * [PopupMenuButton]
+///  * [FlexibleSpaceBar]
+///  * <https://www.google.com/design/spec/layout/structure.html#structure-toolbars>
 class AppBar extends StatelessWidget {
   AppBar({
     Key key,
@@ -19,7 +37,6 @@ class AppBar extends StatelessWidget {
     this.title,
     this.actions,
     this.flexibleSpace,
-    this.foregroundOpacity: 1.0,
     this.tabBar,
     this.elevation: 4,
     this.backgroundColor,
@@ -38,28 +55,65 @@ class AppBar extends StatelessWidget {
     assert((tabBar != null) ? flexibleSpace == null : true);
   }
 
+  /// A widget to display before the [title].
+  ///
+  /// If this field is null and this app bar is used in a [Scaffold], the
+  /// [Scaffold] will fill this field with an appropriate widget. For example,
+  /// if the [Scaffold] also has a [Drawer], the [Scaffold] will fill this
+  /// widget with an [IconButton] that opens the drawer. If there's no [Drawer]
+  /// and the parent [Navigator] can go back, the [Scaffold] will fill this
+  /// field with an [IconButton] that calls [Navigator.pop].
   final Widget leading;
+
+  /// The primary widget displayed in the app bar.
+  ///
+  /// Typically a [Text] widget containing a description of the current contents
+  /// of the app.
   final Widget title;
+
+  /// Widgets to display after the title.
+  ///
+  /// Typically these widgets are [IconButton]s representing common operations.
+  /// For less common operations, consider using a [PopupMenuButton] as the
+  /// last action.
   final List<Widget> actions;
-  final WidgetBuilder flexibleSpace;
+
-  final double foregroundOpacity;
+  /// A widget to aid in building scroll-based collapsing app bar effects.
+  ///
+  /// Typically a [FlexibleSpaceBar]. See [FlexibleSpaceBar] for details.
+  final Widget flexibleSpace;
+
+  /// A horizontal strip of tabs to display at the bottom of the app bar.
   final TabBar<dynamic> tabBar;
+
+  /// The z-coordinate at which to place this app bar.
   final int elevation;
+
+  /// The color to use for the the app bar's material.
+  ///
+  /// Defaults to [ThemeData.primaryColor].
   final Color backgroundColor;
+
+  /// The typographic style to use for text in the app bar.
+  ///
+  /// Defaults to [ThemeData.primaryTextTheme].
   final TextTheme textTheme;
+
+  /// The amount of space to inset the contents of the app bar.
   final EdgeInsets padding;
+
   final double _expandedHeight;
   final double _collapsedHeight;
   final double _minimumHeight;
   final double _actualHeight;
 
+  /// Creates a copy of this app bar but with the given fields replaced with the new values.
   AppBar copyWith({
     Key key,
     Widget leading,
     Widget title,
     List<Widget> actions,
-    WidgetBuilder flexibleSpace,
+    Widget flexibleSpace,
-    double foregroundOpacity,
     int elevation,
     Color backgroundColor,
     TextTheme textTheme,
@@ -74,7 +128,6 @@ class AppBar extends StatelessWidget {
       title: title ?? this.title,
       actions: actions ?? this.actions,
       flexibleSpace: flexibleSpace ?? this.flexibleSpace,
-      foregroundOpacity: foregroundOpacity ?? this.foregroundOpacity,
       tabBar: tabBar ?? this.tabBar,
       elevation: elevation ?? this.elevation,
       backgroundColor: backgroundColor ?? this.backgroundColor,
@@ -90,8 +143,10 @@ class AppBar extends StatelessWidget {
 
   double get _toolBarHeight => kToolBarHeight;
 
+  /// The height of this app bar when fully expanded.
   double get expandedHeight => _expandedHeight ?? (_toolBarHeight + (_tabBarHeight ?? 0.0));
 
+  /// The height of this app bar when fully collapsed.
   double get collapsedHeight => _collapsedHeight ?? (_toolBarHeight + (_tabBarHeight ?? 0.0));
 
   double get minimumHeight => _minimumHeight ?? _tabBarHeight ?? _toolBarHeight;
@@ -202,7 +257,7 @@ class AppBar extends StatelessWidget {
     if (flexibleSpace != null) {
       appBar = new Stack(
         children: <Widget>[
-          flexibleSpace(context),
+          flexibleSpace,
           new Align(child: appBar, alignment: FractionalOffset.topLeft)
         ]
       );

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

@@ -15,7 +15,36 @@ const double _kCloseProgressThreshold = 0.5;
 const Color _kTransparent = const Color(0x00000000);
 const Color _kBarrierColor = Colors.black54;
 
+/// A material design bottom sheet.
+///
+/// There are two kinds of bottom sheets in material design:
+///
+///  * _Persistent_. A persistent bottom sheet shows information that
+///    supplements the primary content of the app. A persistent bottom sheet
+///    remains visible even when the user interacts with other parts of the app.
+///    Persistent bottom sheets can be created and displayed with the
+///    [Scaffold.showBottomSheet] function.
+///
+///  * _Modal_. A modal bottom sheet is an alternative to a menu or a dialog and
+///    prevents the user from interacting with the rest of the app. Modal bottom
+///    sheets can be created and displayed with the [showModalBottomSheet]
+///    function.
+///
+/// The [BottomSheet] widget itself is rarely used directly. Instead, prefer to
+/// create a persistent bottom sheet with [Scaffold.showBottomSheet] and a modal
+/// bottom sheet with [showModalBottomSheet].
+///
+/// See also:
+///
+///  * [Scaffold.showBottomSheet]
+///  * [showModalBottomSheet]
+///  * <https://www.google.com/design/spec/components/bottom-sheets.html>
 class BottomSheet extends StatefulWidget {
+  /// Creates a bottom sheet.
+  ///
+  /// Typically, bottom sheets are created implicitly by
+  /// [Scaffold.showBottomSheet], for persistent bottom sheets, or by
+  /// [showModalBottomSheet], for modal bottom sheets.
   BottomSheet({
     Key key,
     this.animationController,
@@ -25,16 +54,29 @@ class BottomSheet extends StatefulWidget {
     assert(onClosing != null);
   }
 
-  /// The animation that controls the bottom sheet's position. The BottomSheet
+  /// The animation that controls the bottom sheet's position.
-  /// widget will manipulate the position of this animation, it is not just a
+  ///
-  /// passive observer.
+  /// The BottomSheet widget will manipulate the position of this animation, it
+  /// is not just a passive observer.
   final AnimationController animationController;
+
+  /// Called when the bottom sheet begins to close.
+  ///
+  /// A bottom sheet might be be prevented from closing (e.g., by user
+  /// interaction) even after this callback is called. For this reason, this
+  /// callback might be call multiple times for a given bottom sheet.
   final VoidCallback onClosing;
+
+  /// A builder for the contents of the sheet.
+  ///
+  /// The bottom sheet will wrap the widget produced by this builder in a
+  /// [Material] widget.
   final WidgetBuilder builder;
 
   @override
   _BottomSheetState createState() => new _BottomSheetState();
 
+  /// Creates an animation controller suitable for controlling a [BottomSheet].
   static AnimationController createAnimationController() {
     return new AnimationController(
       duration: _kBottomSheetDuration,
@@ -183,6 +225,25 @@ class _ModalBottomSheetRoute<T> extends PopupRoute<T> {
   }
 }
 
+/// Shows a modal material design bottom sheet.
+///
+/// A modal bottom sheet is an alternative to a menu or a dialog and prevents
+/// the user from interacting with the rest of the app.
+///
+/// A closely related widget is a persistent bottom sheet, which shows
+/// information that supplements the primary content of the app without
+/// preventing the use from interacting with the app. Persistent bottom sheets
+/// 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.
+///
+/// See also:
+///
+///  * [BottomSheet]
+///  * [Scaffold.showBottomSheet]
+///  * <https://www.google.com/design/spec/components/bottom-sheets.html#bottom-sheets-modal-bottom-sheets>
 Future<dynamic/*=T*/> showModalBottomSheet/*<T>*/({ BuildContext context, WidgetBuilder builder }) {
   assert(context != null);
   assert(builder != null);

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

@@ -10,8 +10,28 @@ import 'ink_well.dart';
 import 'material.dart';
 import 'theme.dart';
 
-enum ButtonColor { normal, accent }
+/// Whether a button should use the accent color for its text.
+///
+/// See also:
+///
+///  * [ButtonTheme]
+///  * [RaisedButton]
+///  * [FlatButton]
+enum ButtonColor {
+  /// The button should use the normal color (e.g., black or white depending on the [ThemeData.brightness]) for its text.
+  normal,
 
+  /// The button should use the accent color (e.g., [ThemeData.accentColor]) for its text.
+  accent,
+}
+
+/// Defines the button color used by a widget subtree.
+///
+/// See also:
+///
+///  * [ButtonColor]
+///  * [RaisedButton]
+///  * [FlatButton]
 class ButtonTheme extends InheritedWidget {
   ButtonTheme({
     Key key,
@@ -21,6 +41,7 @@ class ButtonTheme extends InheritedWidget {
     assert(child != null);
   }
 
+  /// The button color that this subtree should use.
   final ButtonColor color;
 
   /// The color from the closest instance of this class that encloses the given context.
@@ -45,6 +66,7 @@ abstract class MaterialButton extends StatefulWidget {
   MaterialButton({
     Key key,
     this.child,
+    this.colorBrightness,
     this.textTheme,
     this.textColor,
     this.disabledTextColor,
@@ -54,10 +76,24 @@ abstract class MaterialButton extends StatefulWidget {
   /// The widget below this widget in the tree.
   final Widget child;
 
+  /// The theme brightness to use for this button.
+  ///
+  /// Defaults to the brightness from [ThemeData.brightness].
+  final ThemeBrightness colorBrightness;
+
+  /// The color scheme to use for this button's text.
+  ///
+  /// Defaults to the button color from [ButtonTheme].
   final ButtonColor textTheme;
 
+  /// The color to use for this button's text.
+  ///
+  /// Defaults to the color determined by the [textTheme].
   final Color textColor;
 
+  /// The color to use for this button's text when the button cannot be pressed.
+  ///
+  /// Defaults to a color derived from the [Theme].
   final Color disabledTextColor;
 
   /// The callback that is invoked when the button is tapped or otherwise activated.
@@ -77,14 +113,25 @@ abstract class MaterialButton extends StatefulWidget {
   }
 }
 
+/// A state object for [MaterialButton].
+///
+/// Subclasses of [MaterialButton] should use a subclass of
+/// [MaterialButtonState] for their state objects.
 abstract class MaterialButtonState<T extends MaterialButton> extends State<T> {
+  /// Whether this button is in the process of potentially being pressed.
   bool highlight = false;
 
+  /// The z-coordinate at which to place this button.
   int get elevation;
-  Color getColor(BuildContext context);
-  ThemeBrightness getColorBrightness(BuildContext context);
 
-  Color getTextColor(BuildContext context) {
+  /// The color to use for the button's material.
+  Color getColor(BuildContext context);
+
+  ThemeBrightness _getColorBrightness(BuildContext context) {
+    return config.colorBrightness ?? Theme.of(context).brightness;
+  }
+
+  Color _getTextColor(BuildContext context) {
     if (config.enabled) {
       if (config.textColor != null)
         return config.textColor;
@@ -92,7 +139,7 @@ abstract class MaterialButtonState<T extends MaterialButton> extends State<T> {
         case ButtonColor.accent:
           return Theme.of(context).accentColor;
         case ButtonColor.normal:
-          switch (getColorBrightness(context)) {
+          switch (_getColorBrightness(context)) {
             case ThemeBrightness.light:
               return Colors.black87;
             case ThemeBrightness.dark:
@@ -102,7 +149,7 @@ abstract class MaterialButtonState<T extends MaterialButton> extends State<T> {
     }
     if (config.disabledTextColor != null)
       return config.disabledTextColor;
-    switch (getColorBrightness(context)) {
+    switch (_getColorBrightness(context)) {
       case ThemeBrightness.light:
         return Colors.black26;
       case ThemeBrightness.dark:
@@ -131,7 +178,7 @@ abstract class MaterialButtonState<T extends MaterialButton> extends State<T> {
         )
       )
     );
-    TextStyle style = Theme.of(context).textTheme.button.copyWith(color: getTextColor(context));
+    TextStyle style = Theme.of(context).textTheme.button.copyWith(color: _getTextColor(context));
     int elevation = this.elevation;
     Color color = getColor(context);
     if (elevation > 0 || color != null) {

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

@@ -10,7 +10,11 @@ const EdgeInsets _kCardMargins = const EdgeInsets.all(4.0);
 
 /// A material design card
 ///
-/// <https://www.google.com/design/spec/components/cards.html>
+/// See also:
+///
+///  * [Dialog]
+///  * [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);
 

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

@@ -33,7 +33,7 @@ const TextStyle _kLabelStyle = const TextStyle(
 /// See also:
 ///
 ///  * [CircleAvatar]
-///  * https://www.google.com/design/spec/components/chips.html
+///  * <https://www.google.com/design/spec/components/chips.html>
 class Chip extends StatelessWidget {
   const Chip({
     Key key,

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

@@ -48,7 +48,7 @@ class Drawer extends StatelessWidget {
     this.child
   }) : super(key: key);
 
-  /// The height at which to place this drawer.
+  /// The z-coordinate at which to place this drawer.
   final int elevation;
 
   /// The widget below this widget in the tree.

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

@@ -280,7 +280,7 @@ class DropDownButton<T> extends StatefulWidget {
   /// Called when the user selects an item.
   final ValueChanged<T> onChanged;
 
-  /// The height at which to place the menu when open.
+  /// The z-coordinate at which to place the menu when open.
   final int elevation;
 
   @override

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

@@ -32,20 +32,21 @@ import 'theme.dart';
 ///
 ///  * [RaisedButton]
 ///  * [DropDownButton]
-///  * https://www.google.com/design/spec/components/buttons.html
+///  * <https://www.google.com/design/spec/components/buttons.html>
 class FlatButton extends MaterialButton {
   FlatButton({
     Key key,
     Widget child,
+    ThemeBrightness colorBrightness,
     ButtonColor textTheme,
     Color textColor,
     Color disabledTextColor,
     this.color,
-    this.colorBrightness,
     this.disabledColor,
     VoidCallback onPressed
   }) : super(key: key,
              child: child,
+             colorBrightness: colorBrightness,
              textTheme: textTheme,
              textColor: textColor,
              disabledTextColor: disabledTextColor,
@@ -60,9 +61,6 @@ class FlatButton extends MaterialButton {
   /// value.
   final Color disabledColor;
 
-  /// Controls the default text color if the text color isn't explicit set.
-  final ThemeBrightness colorBrightness;
-
   @override
   _FlatButtonState createState() => new _FlatButtonState();
 }
@@ -77,9 +75,4 @@ class _FlatButtonState extends MaterialButtonState<FlatButton> {
       return config.disabledColor;
     return config.color;
   }
-
-  @override
-  ThemeBrightness getColorBrightness(BuildContext context) {
-    return config.colorBrightness ?? Theme.of(context).brightness;
-  }
 }

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

@@ -63,7 +63,7 @@ class FloatingActionButton extends StatefulWidget {
   /// If this is set to null, the button will be disabled.
   final VoidCallback onPressed;
 
-  /// The height at which to place this button.
+  /// The z-coordinate at which to place this button.
   final int elevation;
 
   final int highlightElevation;

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

@@ -91,7 +91,7 @@ class Material extends StatefulWidget {
 
   final MaterialType type;
 
-  /// The height at which to place this material.
+  /// The z-coordinate at which to place this material.
   final int elevation;
 
   final Color color;

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

@@ -409,7 +409,7 @@ class PopupMenuButton<T> extends StatefulWidget {
 
   final String tooltip;
 
-  /// The height at which to place the menu when open.
+  /// The z-coordinate at which to place the menu when open.
   final int elevation;
 
   /// The widget below this widget in the tree.

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

@@ -35,8 +35,8 @@ class RaisedButton extends MaterialButton {
   RaisedButton({
     Key key,
     Widget child,
+    ThemeBrightness colorBrightness,
     this.color,
-    this.colorBrightness,
     this.disabledColor,
     this.elevation: 2,
     this.highlightElevation: 8,
@@ -44,6 +44,7 @@ class RaisedButton extends MaterialButton {
     VoidCallback onPressed
   }) : super(key: key,
              child: child,
+             colorBrightness: colorBrightness,
              onPressed: onPressed);
 
   /// The color of the button, as printed on the [Material]. Defaults to null,
@@ -55,16 +56,13 @@ class RaisedButton extends MaterialButton {
   /// value.
   final Color disabledColor;
 
-  /// Controls the default text color if the text color isn't explicit set.
+  /// The z-coordinate at which to place this button.
-  final ThemeBrightness colorBrightness;
-
-  /// The height at which to place this button.
   final int elevation;
 
-  /// The height at which to place this button when highlighted.
+  /// The z-coordinate at which to place this button when highlighted.
   final int highlightElevation;
 
-  /// The height at which to place this button when disabled.
+  /// The z-coordinate at which to place this button when disabled.
   final int disabledElevation;
 
   @override
@@ -98,9 +96,4 @@ class _RaisedButtonState extends MaterialButtonState<RaisedButton> {
       }
     }
   }
-
-  @override
-  ThemeBrightness getColorBrightness(BuildContext context) {
-    return config.colorBrightness ?? Theme.of(context).brightness;
-  }
 }

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

@@ -238,16 +238,27 @@ class ScaffoldState extends State<Scaffold> {
 
   AnimationController _appBarController;
 
+  /// The animation controlling the size of the app bar.
+  ///
+  /// Useful for linking animation effects to the expansion and collapse of the
+  /// app bar.
   Animation<double> get appBarAnimation => _appBarController.view;
 
+  /// The height of the app bar when fully expanded.
+  ///
+  /// See [AppBar.expandedHeight].
   double get appBarHeight => config.appBar?.expandedHeight ?? 0.0;
 
   // DRAWER API
 
   final GlobalKey<DrawerControllerState> _drawerKey = new GlobalKey<DrawerControllerState>();
 
+  /// Opens the [Drawer] (if any).
+  ///
+  /// If the scaffold has a non-null [Scaffold.drawer], this function will cause
+  /// the drawer to begin its entrance animation.
   void openDrawer() {
-    _drawerKey.currentState.open();
+    _drawerKey.currentState?.open();
   }
 
   // SNACKBAR API
@@ -256,6 +267,12 @@ class ScaffoldState extends State<Scaffold> {
   AnimationController _snackBarController;
   Timer _snackBarTimer;
 
+  /// Shows a [SnackBar] at the bottom fo the scaffold.
+  ///
+  /// A scaffold can show at most one snack bar at a time. If this function is
+  /// called while another snack bar is already visible, the given snack bar
+  /// will be added to a queue and displayed after the earlier snack bars have
+  /// closed.
   ScaffoldFeatureController<SnackBar, Null> showSnackBar(SnackBar snackbar) {
     _snackBarController ??= SnackBar.createAnimationController()
       ..addStatusListener(_handleSnackBarStatusChange);
@@ -304,6 +321,10 @@ class ScaffoldState extends State<Scaffold> {
     }
   }
 
+  /// Removes the current [SnackBar] (if any) immediately.
+  ///
+  /// The removed snack bar does not run its normal exit animation. If there are
+  /// any queued snack bars, they begin their entrance animation immediately.
   void removeCurrentSnackBar() {
     if (_snackBars.isEmpty)
       return;
@@ -330,6 +351,25 @@ class ScaffoldState extends State<Scaffold> {
   List<Widget> _dismissedBottomSheets;
   PersistentBottomSheetController<dynamic> _currentBottomSheet;
 
+  /// Shows a persistent material design bottom sheet.
+  ///
+  /// A persistent bottom sheet shows information that supplements the primary
+  /// content of the app. A persistent bottom sheet remains visible even when
+  /// the user interacts with other parts of the app.
+  ///
+  /// A closely related widget is  a modal bottom sheet, which is an alternative
+  /// to a menu or a dialog and prevents the user from interacting with the rest
+  /// of the app. Modal bottom sheets can be created and displayed with the
+  /// [showModalBottomSheet] function.
+  ///
+  /// Returns a contoller that can be used to close and otherwise manipulate the
+  /// button sheet.
+  ///
+  /// See also:
+  ///
+  ///  * [BottomSheet]
+  ///  * [showModalBottomSheet]
+  ///  * <https://www.google.com/design/spec/components/bottom-sheets.html#bottom-sheets-persistent-bottom-sheets>
   PersistentBottomSheetController<dynamic/*=T*/> showBottomSheet/*<T>*/(WidgetBuilder builder) {
     if (_currentBottomSheet != null) {
       _currentBottomSheet.close();

packages/flutter/lib/src/painting/text_style.dart

@@ -72,8 +72,7 @@ class TextStyle {
   /// The style in which to paint the text decorations (e.g., dashed).
   final TextDecorationStyle decorationStyle;
 
-  /// Returns a new text style that matches this text style but with the given
+  /// Creates a copy of this text style but with the given fields replaced with the new values.
-  /// values replaced.
   TextStyle copyWith({
     Color color,
     String fontFamily,

packages/flutter/lib/src/rendering/box.dart

@@ -91,7 +91,7 @@ class BoxConstraints extends Constraints {
       minHeight = height != null ? height : double.INFINITY,
       maxHeight = height != null ? height : double.INFINITY;
 
-  /// Returns new box constraints that remove the minimum width and height requirements.
+  /// Creates a copy of this box constraints but with the given fields replaced with the new values.
   BoxConstraints copyWith({
     double minWidth,
     double maxWidth,

packages/flutter/lib/src/widgets/editable.dart

@@ -125,6 +125,7 @@ class InputValue {
     composing.hashCode
   );
 
+  /// Creates a copy of this input value but with the given fields replaced with the new values.
   InputValue copyWith({
     String text,
     TextSelection selection,