Add dartdoc for child widgets

This patch adds a consistent, simple description for the common pattern of
having a single child widget.

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

@@ -50,9 +50,13 @@ abstract class MaterialButton extends StatefulWidget {
     this.onPressed
   }) : super(key: key);
 
+  /// The widget below this widget in the tree.
   final Widget child;
+
   final ButtonColor textTheme;
+
   final Color textColor;
+
   final Color disabledTextColor;
 
   /// The callback that is invoked when the button is tapped or otherwise activated.

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

@@ -14,7 +14,10 @@ const EdgeInsets _kCardMargins = const EdgeInsets.all(4.0);
 class Card extends StatelessWidget {
   const Card({ Key key, this.child, this.color }) : super(key: key);
 
+  /// The widget below this widget in the tree.
   final Widget child;
+
+  /// The color of material used for this card.
   final Color color;
 
   @override

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

@@ -23,6 +23,7 @@ class CircleAvatar extends StatelessWidget {
     this.radius: 40.0
   }) : super(key: key);
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   /// The color with which to fill the circle. Changing the background

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

@@ -34,6 +34,8 @@ class Drawer extends StatelessWidget {
   }) : super(key: key);
 
   final int elevation;
+
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override

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

@@ -14,6 +14,7 @@ import 'theme.dart';
 class DrawerHeader extends StatelessWidget {
   const DrawerHeader({ Key key, this.child }) : super(key: key);
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override

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

@@ -20,9 +20,14 @@ class DrawerItem extends StatelessWidget {
     this.selected: false
   }) : super(key: key);
 
+  /// The icon to display before the child widget.
   final IconData icon;
+
+  /// The widget below this widget in the tree.
   final Widget child;
+
   final VoidCallback onPressed;
+
   final bool selected;
 
   Color _getIconColor(ThemeData themeData) {

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

@@ -219,7 +219,12 @@ class DropDownMenuItem<T> extends StatelessWidget {
     this.child
   }) : super(key: key);
 
+  /// The widget below this widget in the tree.
   final Widget child;
+
+  /// The value to return if the user selects this menu item.
+  ///
+  /// Eventually returned in a call to [DropDownButton.onChanged].
   final T value;
 
   @override

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

@@ -44,16 +44,25 @@ class FloatingActionButton extends StatefulWidget {
     this.mini: false
   }) : super(key: key);
 
+  /// The widget below this widget in the tree.
   final Widget child;
+
   final String tooltip;
+
+  /// The color to use when filling the button.
+  ///
+  /// Defaults to the accent color of the current theme.
   final Color backgroundColor;
 
   /// The callback that is invoked when the button is tapped or otherwise activated.
   ///
   /// If this is set to null, the button will be disabled.
   final VoidCallback onPressed;
+
   final int elevation;
+
   final int highlightElevation;
+
   final bool mini;
 
   @override

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

@@ -11,8 +11,13 @@ class GridTile extends StatelessWidget {
     assert(child != null);
   }
 
+  /// The widget to show over the top of this grid tile.
   final Widget header;
+
+  /// The widget to show over the bottom of this grid tile.
   final Widget footer;
+
+  /// The widget that fills the tile.
   final Widget child;
 
   @override

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

@@ -36,12 +36,19 @@ class InkResponse extends StatefulWidget {
     this.highlightShape: BoxShape.circle
   }) : super(key: key);
 
+  /// The widget below this widget in the tree.
   final Widget child;
+
   final GestureTapCallback onTap;
+
   final GestureTapCallback onDoubleTap;
+
   final GestureLongPressCallback onLongPress;
+
   final ValueChanged<bool> onHighlightChanged;
+
   final bool containedInWell;
+
   final BoxShape highlightShape;
 
   @override

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

@@ -86,10 +86,15 @@ class Material extends StatefulWidget {
     assert(elevation != null);
   }
 
+  /// The widget below this widget in the tree.
   final Widget child;
+
   final MaterialType type;
+
   final int elevation;
+
   final Color color;
+
   final TextStyle textStyle;
 
   /// The ink controller from the closest instance of this class that encloses the given context.

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

@@ -65,6 +65,7 @@ class PopupMenuItem<T> extends PopupMenuEntry<T> {
   @override
   final bool enabled;
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override
@@ -395,10 +396,16 @@ class PopupMenuButton<T> extends StatefulWidget {
   }) : super(key: key);
 
   final List<PopupMenuEntry<T>> items;
+
   final T initialValue;
+
   final PopupMenuItemSelected<T> onSelected;
+
   final String tooltip;
+
   final int elevation;
+
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override

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

@@ -429,8 +429,12 @@ class TabBarSelection<T> extends StatefulWidget {
   }
 
   final T value;
+
   List<T> values;
+
   final ValueChanged<T> onChanged;
+
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override

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

@@ -66,8 +66,10 @@ class AnimatedTheme extends ImplicitlyAnimatedWidget {
     assert(data != null);
   }
 
+  /// Specifies the color and typography values for descendant widgets.
   final ThemeData data;
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override

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

@@ -50,18 +50,32 @@ class Tooltip extends StatefulWidget {
   }
 
   final String message;
+
   final Color backgroundColor;
+
   final Color textColor;
+
   final TextStyle style;
+
   final double opacity;
+
   final double borderRadius;
+
   final double height;
+
   final EdgeInsets padding;
+
   final double verticalOffset;
+
   final EdgeInsets screenEdgeMargin;
+
   final bool preferBelow;
+
   final Duration fadeDuration;
+
   final Duration showDuration;
+
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override

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

@@ -206,8 +206,12 @@ class AssetVendor extends StatefulWidget {
   }) : super(key: key);
 
   final AssetBundle bundle;
+
   final double devicePixelRatio;
+
+  /// The widget below this widget in the tree.
   final Widget child;
+
   final ImageDecoder imageDecoder;
 
   @override

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

@@ -971,7 +971,7 @@ class Container extends StatelessWidget {
     assert(decoration == null || decoration.debugAssertValid());
   }
 
-  /// The child to contain in the container.
+  /// The child contained by the container.
   ///
   /// If null, the container will expand to fill all available space in its parent.
   final Widget child;
@@ -2502,6 +2502,7 @@ class KeyedSubtree extends StatelessWidget {
   KeyedSubtree({ Key key, this.child })
     : super(key: key);
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override

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

@@ -189,8 +189,11 @@ class RenderObjectToWidgetAdapter<T extends RenderObject> extends RenderObjectWi
     this.debugShortDescription
   }) : container = container, super(key: new GlobalObjectKey(container));
 
+  /// The widget below this widget in the tree.
   final Widget child;
+
   final RenderObjectWithChildMixin<T> container;
+
   final String debugShortDescription;
 
   @override

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

@@ -60,6 +60,7 @@ class CheckedModeBanner extends StatelessWidget {
     this.child
   }) : super(key: key);
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override

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

@@ -68,6 +68,7 @@ class Dismissable extends StatefulWidget {
     assert(secondaryBackground != null ? background != null : true);
   }
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   /// A widget that is stacked behind the child. If secondaryBackground is also

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

@@ -53,6 +53,8 @@ abstract class DraggableBase<T> extends StatefulWidget {
   }
 
   final T data;
+
+  /// The widget below this widget in the tree.
   final Widget child;
 
   /// The widget to show instead of [child] when a drag is under way.

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

@@ -101,6 +101,7 @@ class Focus extends StatefulWidget {
     assert(key != null);
   }
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   /// The key that currently has focus globally in the entire focus tree.

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

@@ -554,6 +554,7 @@ abstract class LeafRenderObjectWidget extends RenderObjectWidget {
 abstract class SingleChildRenderObjectWidget extends RenderObjectWidget {
   const SingleChildRenderObjectWidget({ Key key, this.child }) : super(key: key);
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override

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

@@ -97,6 +97,7 @@ class GestureDetector extends StatelessWidget {
     });
   }
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   /// A pointer that might cause a tap has contacted the screen at a particular
@@ -289,6 +290,7 @@ class RawGestureDetector extends StatefulWidget {
     assert(excludeFromSemantics != null);
   }
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   final Map<Type, GestureRecognizerFactory> gestures;

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

@@ -71,6 +71,7 @@ class GridPaper extends StatelessWidget {
   /// The number of minor divisions within each major division.
   final int subDivisions;
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override

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

@@ -88,7 +88,10 @@ class Hero extends StatefulWidget {
   }
 
   final Object tag;
+
+  /// The widget below this widget in the tree.
   final Widget child;
+
   final int turns;
 
   /// If true, the hero will always animate, even if it has no matching hero to

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

@@ -206,6 +206,7 @@ class AnimatedContainer extends ImplicitlyAnimatedWidget {
     assert(padding == null || padding.isNonNegative);
   }
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   /// Additional constraints to apply to the child.
@@ -352,6 +353,7 @@ class AnimatedPositioned extends ImplicitlyAnimatedWidget {
        bottom = null,
        super(key: key, curve: curve, duration: duration);
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   /// The offset of the child's left edge from the left of the stack.

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

@@ -144,6 +144,7 @@ class Mimic extends StatelessWidget {
 class Mimicable extends StatefulWidget {
   Mimicable({ Key key, this.child }) : super(key: key);
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override

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

@@ -31,6 +31,7 @@ class NotificationListener<T extends Notification> extends StatelessWidget {
     this.onNotification
   }) : super(key: key);
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   /// Called when a notification of the appropriate type arrives at this location in the tree.

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

@@ -96,6 +96,7 @@ class PageStorage extends StatelessWidget {
     this.bucket
   }) : super(key: key);
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   /// The page storage bucket to use for this subtree.

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

@@ -20,7 +20,10 @@ class RawKeyboardListener extends StatefulWidget {
   }
 
   final bool focused;
+
   final ValueChanged<mojom.InputEvent> onKey;
+
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override

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

@@ -630,6 +630,7 @@ class ScrollableViewport extends Scrollable {
     onScrollEnd: onScrollEnd
   );
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override

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

@@ -18,6 +18,7 @@ import 'gesture_detector.dart';
 class SemanticsDebugger extends StatefulWidget {
   const SemanticsDebugger({ Key key, this.child }) : super(key: key);
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override

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

@@ -22,6 +22,7 @@ class Title extends StatelessWidget {
   /// A color that the window manager should use to identify this app.
   final Color color;
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override

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

@@ -103,6 +103,7 @@ class SlideTransition extends AnimatedWidget {
   /// location and you want the user to benefit from "muscle memory".
   final bool transformHitTests;
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override
@@ -137,6 +138,7 @@ class ScaleTransition extends AnimatedWidget {
   /// an alignment of (0.5, 1.0).
   final FractionalOffset alignment;
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override
@@ -166,6 +168,7 @@ class RotationTransition extends AnimatedWidget {
   /// rotated v * 2 * pi radians before being painted.
   final Animation<double> turns;
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override
@@ -203,6 +206,7 @@ class SizeTransition extends AnimatedWidget {
   /// How to align the child along the axis that sizeFactor is modifying.
   final double axisAlignment;
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override
@@ -239,6 +243,7 @@ class FadeTransition extends AnimatedWidget {
   /// completely transparent.
   final Animation<double> opacity;
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override
@@ -277,6 +282,7 @@ class PositionedTransition extends AnimatedWidget {
   /// The animation that controls the child's size and position.
   final Animation<RelativeRect> rect;
 
+  /// The widget below this widget in the tree.
   final Widget child;
 
   @override