Add more dartdoc to material.dart (#3261)

Now past halfway though material.dart by files.

examples/material_gallery/lib/demo/flexible_space_demo.dart

@@ -124,7 +124,7 @@ class FlexibleSpaceDemoState extends State<FlexibleSpaceDemo> {
           ],
           flexibleSpace: new FlexibleSpaceBar(
             title : new Text('Ali Connors'),
-            image: new AssetImage(
+            background: new AssetImage(
               name: 'packages/flutter_gallery_assets/ali_connors.png',
               fit: ImageFit.cover,
               height: _appBarHeight

examples/material_gallery/lib/gallery/home.dart

@@ -84,8 +84,8 @@ class GalleryHomeState extends State<GalleryHome> {
       appBar: new AppBar(
         expandedHeight: _kFlexibleSpaceMaxHeight,
         flexibleSpace: new FlexibleSpaceBar(
-          image: new GalleryHeader(),
-          title: new Text("Flutter gallery")
+          title: new Text("Flutter gallery"),
+          background: new GalleryHeader()
         )
       ),
       scrollableKey: _listKey,

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

@@ -11,11 +11,36 @@ import 'constants.dart';
 import 'scaffold.dart';
 import 'theme.dart';
 
+/// The part of a material design [AppBar] that expands and collapses.
+///
+/// Most commonly used in in the [AppBar.flexibleSpace] field, a flexible space
+/// bar expands and contracts as the app scrolls so that the [AppBar] reaches
+/// from the top of the app to the top of the scrolling contents of the app.
+///
+/// Requires one of its ancestors to be a [Scaffold] widget because the
+/// [Scaffold] coordinates the scrolling effect between the flexible space and
+/// its body.
+///
+/// See also:
+///  * [AppBar]
+///  * [Scaffold]
+///  * <https://www.google.com/design/spec/patterns/scrolling-techniques.html>
 class FlexibleSpaceBar extends StatefulWidget {
-  FlexibleSpaceBar({ Key key, this.title, this.image }) : super(key: key);
+  /// Creates a flexible space bar.
+  ///
+  /// Most commonly used in the [AppBar.flexibleSpace] field. Requires one of
+  /// its ancestors to be a [Scaffold] widget.
+  FlexibleSpaceBar({ Key key, this.title, this.background }) : super(key: key);
 
+  /// The primary contents of the flexible space bar when expanded.
+  ///
+  /// Typically a [Text] widget.
   final Widget title;
-  final Widget image;
+
+  /// Shown behind the [title] when expanded.
+  ///
+  /// Typically an [AssetImage] widget with [AssetImage.fit] set to [ImageFit.cover].
+  final Widget background;
 
   @override
   _FlexibleSpaceBarState createState() => new _FlexibleSpaceBarState();
@@ -47,7 +72,7 @@ class _FlexibleSpaceBarState extends State<FlexibleSpaceBar> {
     final List<Widget> children = <Widget>[];
 
     // background image
-    if (config.image != null) {
+    if (config.background != null) {
       final double fadeStart = (appBarHeight - toolBarHeight * 2.0) / appBarHeight;
       final double fadeEnd = (appBarHeight - toolBarHeight) / appBarHeight;
       final CurvedAnimation opacityCurve = new CurvedAnimation(
@@ -63,7 +88,7 @@ class _FlexibleSpaceBarState extends State<FlexibleSpaceBar> {
           opacity: new Tween<double>(begin: 1.0, end: 0.0).evaluate(opacityCurve),
           child: new SizedBox(
             height: appBarHeight + statusBarHeight,
-            child: config.image
+            child: config.background
           )
         )
        ));

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

@@ -19,24 +19,29 @@ const double _kSizeMini = 40.0;
 const Duration _kChildSegue = const Duration(milliseconds: 400);
 const Interval _kChildSegueInterval = const Interval(0.65, 1.0);
 
-/// A material design "floating action button".
+/// A material design floating action button.
 ///
 /// A floating action button is a circular icon button that hovers over content
-/// to promote a primary action in the application.
+/// to promote a primary action in the application. Floating action buttons are
+/// most commonly used in the [Scaffold.floatingActionButton] field.
 ///
 /// Use at most a single floating action button per screen. Floating action
 /// buttons should be used for positive actions such as "create", "share", or
 /// "navigate".
 ///
 /// If the [onPressed] callback is not specified or null, then the button will
-/// be disabled, will not react to touch.
+/// be disabled and will not react to touch.
 ///
 /// See also:
 ///
+///  * [Scaffold]
 ///  * [RaisedButton]
 ///  * [FlatButton]
 ///  * <https://www.google.com/design/spec/components/buttons-floating-action-button.html>
 class FloatingActionButton extends StatefulWidget {
+  /// Creates a floating action button.
+  ///
+  /// Most commonly used in the [Scaffold.floatingActionButton] field.
   const FloatingActionButton({
     Key key,
     this.child,
@@ -51,6 +56,10 @@ class FloatingActionButton extends StatefulWidget {
   /// The widget below this widget in the tree.
   final Widget child;
 
+  /// Text that describes the action that will occur when the button is pressed.
+  ///
+  /// This text is displayed when the user long-presses on the button and is
+  /// used for accessibility.
   final String tooltip;
 
   /// The color to use when filling the button.
@@ -66,8 +75,14 @@ class FloatingActionButton extends StatefulWidget {
   /// The z-coordinate at which to place this button.
   final int elevation;
 
+  /// The z-coordinate at which to place this button when the user is touching the button.
   final int highlightElevation;
 
+  /// Controls the size of this button.
+  ///
+  /// By default, floating action buttons are non-mini and have a height and
+  /// width of 56.0 logical pixels. Mini floating action buttons have a height
+  /// and width of 40.0 logical pixels.
   final bool mini;
 
   @override

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

@@ -4,9 +4,21 @@
 
 import 'package:flutter/widgets.dart';
 
-/// Creates a [Stack] with the header anchored across the top or a footer across the
-/// bottom. The [GridTileBar] class can be used to create grid tile headers and footers.
+/// A tile in a material design grid list.
+///
+/// A grid list is a [ScrollableGrid] of tiles in a vertical and horizontal
+/// array. Each tile typically contains some visually rich content (e.g., an
+/// image) together with a [GridTileBar] in either a [header] or a [footer].
+///
+/// See also:
+///
+///  * [ScrollableGrid]
+///  * [GridTileBar]
+///  * <https://www.google.com/design/spec/components/grid-lists.html>
 class GridTile extends StatelessWidget {
+  /// Creates a grid tile.
+  ///
+  /// Must have a child. Does not typically have both a header and a footer.
   GridTile({ Key key, this.header, this.footer, this.child }) : super(key: key) {
     assert(child != null);
   }

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

@@ -9,13 +9,21 @@ import 'icon_theme.dart';
 import 'icon_theme_data.dart';
 import 'typography.dart';
 
-
-/// Typically used to stack a one or two line header or footer on a Grid tile.
-/// The layout is based on the "Grid Lists" section of the Material Design spec:
-/// https://www.google.com/design/spec/components/grid-lists.html#grid-lists-specs
-/// For a one-line header specify [title] and to add a second line specify [subtitle].
-/// Use [leading] or [trailing] to add an icon.
+/// A header used in a material design [GridTile].
+///
+/// Typically used to add a one or two line header or footer on a [GridTile].
+///
+/// For a one-line header, include a [title] widget. To add a second line, also
+/// include a [subtitle] wiget. Use [leading] or [trailing] to add an icon.
+///
+/// See also:
+///
+///  * [GridTile]
+///  * <https://www.google.com/design/spec/components/grid-lists.html#grid-lists-specs>
 class GridTileBar extends StatelessWidget {
+  /// Creates a grid tile bar.
+  ///
+  /// Typically used to with [GridTile].
   GridTileBar({
     Key key,
     this.backgroundColor,
@@ -25,10 +33,29 @@ class GridTileBar extends StatelessWidget {
     this.trailing
   }) : super(key: key);
 
+  /// The color to paint behind the child widgets.
+  ///
+  /// Defaults to transparent.
   final Color backgroundColor;
+
+  /// A widget to display before the title.
+  ///
+  /// Typically an [Icon] or an [IconButton] widget.
   final Widget leading;
+
+  /// The primary content of the list item.
+  ///
+  /// Typically a [Text] widget.
   final Widget title;
+
+  /// Additional content displayed below the title.
+  ///
+  /// Typically a [Text] widget.
   final Widget subtitle;
+
+  /// A widget to display after the title.
+  ///
+  /// Typically an [Icon] or an [IconButton] widget.
   final Widget trailing;
 
   @override

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

@@ -28,6 +28,9 @@ import 'theme.dart';
 ///  * [IconButton], for interactive icons
 ///  * [Icons], for the list of available icons for use with this class
 class Icon extends StatelessWidget {
+  /// Creates an icon.
+  ///
+  /// The size argument is required to be non-null.
   Icon({
     Key key,
     this.icon,

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

@@ -11,21 +11,30 @@ import 'ink_well.dart';
 import 'theme.dart';
 import 'tooltip.dart';
 
-/// A material design "icon button".
+/// A material design icon button.
 ///
 /// An icon button is a picture printed on a [Material] widget that reacts to
 /// touches by filling with color.
 ///
-/// Use icon buttons on toolbars.
+/// Icon buttons are commonly used in the [AppBar.actions] field, but they can
+/// be used in many other places as well.
 ///
 /// If the [onPressed] callback is not specified or null, then the button will
 /// be disabled, will not react to touch.
 ///
+/// Requires one of its ancestors to be a [Material] widget.
+///
 /// See also:
 ///
 ///  * [Icons]
 ///  * [AppBar]
 class IconButton extends StatelessWidget {
+  /// Creates an icon button.
+  ///
+  /// Icon buttons are commonly used in the [AppBar.actions] field, but they can
+  /// be used in many other places as well.
+  ///
+  /// Requires one of its ancestors to be a [Material] widget.
   const IconButton({
     Key key,
     this.size: 24.0,

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

@@ -6,7 +6,11 @@ import 'package:flutter/widgets.dart';
 
 import 'icon_theme_data.dart';
 
+/// Controls the color and opacity of icons in a widget subtree.
 class IconTheme extends InheritedWidget {
+  /// Creates an icon theme that controls the color and opacity of descendant widgets.
+  ///
+  /// Both data and child arguments are required to be non-null.
   IconTheme({
     Key key,
     this.data,
@@ -16,6 +20,7 @@ class IconTheme extends InheritedWidget {
     assert(child != null);
   }
 
+  /// The color and opacity to use for icons in this subtree.
   final IconThemeData data;
 
   /// The data from the closest instance of this class that encloses the given context.

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

@@ -5,7 +5,14 @@
 import 'dart:ui' as ui show lerpDouble;
 import 'dart:ui' show Color, hashValues;
 
+/// Defines the color and opacity of icons.
+///
+/// Used by [IconTheme] to control the color and opacity of icons in a widget
+/// subtree.
 class IconThemeData {
+  /// Creates an icon theme data.
+  ///
+  /// The given opacity applies to both explicit and default icon colors.
   const IconThemeData({ this.color, this.opacity });
 
   /// The default color for icons.
@@ -14,8 +21,10 @@ class IconThemeData {
   /// An opacity to apply to both explicit and default icon colors.
   final double opacity;
 
+  /// Normalizes the given opacity to be between 0.0 and 1.0 (inclusive).
   double get clampedOpacity => (opacity ?? 1.0).clamp(0.0, 1.0);
 
+  /// Linearly interpolate between two icon theme data objects.
   static IconThemeData lerp(IconThemeData begin, IconThemeData end, double t) {
     return new IconThemeData(
       color: Color.lerp(begin.color, end.color, t),

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

@@ -2,8 +2,17 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+/// A description of a material design icon.
+///
+/// See [Icons] for a number of predefined icons.
 class IconData {
+  /// Creates icon data.
+  ///
+  /// Rarely used directly. Instead, consider using one of the predefined icons
+  /// from the [Icons] collection.
   const IconData(this.codePoint);
+
+  /// The unicode code point at which this icon is stored in the icon font.
   final int codePoint;
 
   @override

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

@@ -12,7 +12,7 @@ import 'debug.dart';
 import 'material.dart';
 import 'theme.dart';
 
-/// An area of a Material that responds to touch. Has a configurable shape and
+/// An area of a [Material] that responds to touch. Has a configurable shape and
 /// can be configured to clip splashes that extend outside its bounds or not.
 ///
 /// For a variant of this widget that is specialised for rectangular areas that
@@ -25,6 +25,9 @@ import 'theme.dart';
 ///
 ///     assert(debugCheckHasMaterial(context));
 class InkResponse extends StatefulWidget {
+  /// Creates an area of a [Material] that responds to touch.
+  ///
+  /// Must have an ancestor [Material] widget in which to cause ink reactions.
   InkResponse({
     Key key,
     this.child,
@@ -32,23 +35,33 @@ class InkResponse extends StatefulWidget {
     this.onDoubleTap,
     this.onLongPress,
     this.onHighlightChanged,
-    this.containedInWell: false,
+    this.containedInkWell: false,
     this.highlightShape: BoxShape.circle
   }) : super(key: key);
 
   /// The widget below this widget in the tree.
   final Widget child;
 
+  /// Called when the user taps this part of the material
   final GestureTapCallback onTap;
 
+  /// Called when the user double taps this part of the material.
   final GestureTapCallback onDoubleTap;
 
+  /// Called when the user long-presses on this part of the material.
   final GestureLongPressCallback onLongPress;
 
+  /// Called when this part of the material either becomes highlighted or stops behing highlighted.
+  ///
+  /// The value passed to the callback is true if this part of the material has
+  /// become highlighted and false if this part of the material has stopped
+  /// being highlighted.
   final ValueChanged<bool> onHighlightChanged;
 
-  final bool containedInWell;
+  /// Whether this ink response should be clipped its bounds.
+  final bool containedInkWell;
 
+  /// The shape (e.g., circle, rectangle) to use for the highlight drawn around this part of the material.
   final BoxShape highlightShape;
 
   @override
@@ -88,7 +101,6 @@ class _InkResponseState<T extends InkResponse> extends State<T> {
       config.onHighlightChanged(value);
   }
 
-
   void _handleTapDown(Point position) {
     RenderBox referenceBox = context.findRenderObject();
     assert(Material.of(context) != null);
@@ -97,7 +109,7 @@ class _InkResponseState<T extends InkResponse> extends State<T> {
       referenceBox: referenceBox,
       position: referenceBox.globalToLocal(position),
       color: Theme.of(context).splashColor,
-      containedInWell: config.containedInWell,
+      containedInWell: config.containedInkWell,
       onRemoved: () {
         if (_splashes != null) {
           assert(_splashes.contains(splash));
@@ -188,6 +200,9 @@ class _InkResponseState<T extends InkResponse> extends State<T> {
 ///
 ///     assert(debugCheckHasMaterial(context));
 class InkWell extends InkResponse {
+  /// Creates an ink well.
+  ///
+  /// Must have an ancestor [Material] widget in which to cause ink reactions.
   InkWell({
     Key key,
     Widget child,
@@ -202,7 +217,7 @@ class InkWell extends InkResponse {
     onDoubleTap: onDoubleTap,
     onLongPress: onLongPress,
     onHighlightChanged: onHighlightChanged,
-    containedInWell: true,
+    containedInkWell: true,
     highlightShape: BoxShape.rectangle
   );
 }

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

@@ -26,6 +26,11 @@ import 'theme.dart';
 ///  * [CircleAvatar]
 ///  * <https://www.google.com/design/spec/components/lists.html>
 class ListItem extends StatelessWidget {
+  /// Creates a list item.
+  ///
+  /// If [isThreeLine] is true, then [subtitle] must not be null.
+  ///
+  /// Requires one of its ancestors to be a [Material] widget.
   ListItem({
     Key key,
     this.leading,

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

@@ -407,6 +407,10 @@ class PopupMenuButton<T> extends StatefulWidget {
 
   final PopupMenuItemSelected<T> onSelected;
 
+  /// Text that describes the action that will occur when the button is pressed.
+  ///
+  /// This text is displayed when the user long-presses on the button and is
+  /// used for accessibility.
   final String tooltip;
 
   /// The z-coordinate at which to place the menu when open.