Audit all the "final Widget child" properties. (#13718)

This attempts to apply some of what we learnt from UX studies, namely
that people wonder how to add multiple children to widget that take
one child.

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

@@ -249,6 +249,8 @@ class MaterialButton extends StatefulWidget {
   final VoidCallback onPressed;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// Whether the button is enabled or disabled. Buttons are disabled by default. To

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

@@ -67,6 +67,8 @@ class Card extends StatelessWidget {
   }) : super(key: key);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// The color of material used for this card.

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

@@ -177,6 +177,8 @@ class DataCell {
   /// If the cell has no data, then a [Text] widget with placeholder
   /// text should be provided instead, and [placeholder] should be set
   /// to true.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// Whether the [child] is actually a placeholder.

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

@@ -41,6 +41,8 @@ class Dialog extends StatelessWidget {
   }) : super(key: key);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   Color _getColor(BuildContext context) {

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

@@ -96,6 +96,8 @@ class Drawer extends StatelessWidget {
   /// The widget below this widget in the tree.
   ///
   /// Typically a [SliverList].
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override

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

@@ -67,6 +67,8 @@ class DrawerHeader extends StatelessWidget {
   ///
   /// This widget will be sized to the size of the header. To position the child
   /// precisely, consider using an [Align] or [Center] widget.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override

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

@@ -58,6 +58,8 @@ class FloatingActionButton extends StatefulWidget {
   }) : super(key: key);
 
   /// The widget below this widget in the tree.
+  ///
+  /// Typically an [Icon].
   final Widget child;
 
   /// Text that describes the action that will occur when the button is pressed.

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

@@ -40,6 +40,8 @@ class GridTile extends StatelessWidget {
   final Widget footer;
 
   /// The widget that fills the tile.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override

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

@@ -99,6 +99,8 @@ class InkResponse extends StatefulWidget {
   }) : assert(enableFeedback != null), super(key: key);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// Called when the user taps this part of the material.

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

@@ -396,6 +396,8 @@ class InputDecorator extends StatelessWidget {
   final bool isEmpty;
 
   /// The widget below this widget in the tree.
+  ///
+  /// Typically an [EditableText], [DropdownButton], or [InkWell].
   final Widget child;
 
   static const double _kBottomBorderHeight = 1.0;

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

@@ -125,6 +125,8 @@ class Material extends StatefulWidget {
        super(key: key);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// The kind of material to show (e.g., card or canvas). This

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

@@ -45,6 +45,8 @@ class MaterialSlice extends MergeableMaterialItem {
        super(key);
 
   /// The contents of this slice.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override

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

@@ -94,8 +94,12 @@ class RefreshIndicator extends StatefulWidget {
        assert(notificationPredicate != null),
        super(key: key);
 
+  /// The widget below this widget in the tree.
+  ///
   /// The refresh indicator will be stacked on top of this child. The indicator
   /// will appear when child's Scrollable descendant is over-scrolled.
+  ///
+  /// Typically a [ListView] or [CustomScrollView].
   final Widget child;
 
   /// The distance from the child's top or bottom edge to where the refresh

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

@@ -33,10 +33,12 @@ class Scrollbar extends StatefulWidget {
     @required this.child,
   }) : super(key: key);
 
-  /// The subtree to place inside the [Scrollbar].
+  /// The widget below this widget in the tree.
   ///
-  /// This should include a source of [ScrollNotification] notifications,
-  /// typically a [Scrollable] widget.
+  /// The scrollbar will be stacked on top of this child. This child (and its
+  /// subtree) should include a source of [ScrollNotification] notifications.
+  ///
+  /// Typically a [ListView] or [CustomScrollView].
   final Widget child;
 
   @override

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

@@ -262,7 +262,11 @@ class DefaultTabController extends StatefulWidget {
   /// Defaults to zero.
   final int initialIndex;
 
-  /// This widget's child. Often a [Scaffold] whose [AppBar] includes a [TabBar].
+  /// The widget below this widget in the tree.
+  ///
+  /// Typically a [Scaffold] whose [AppBar] includes a [TabBar].
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// The closest instance of this class that encloses the given context.

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

@@ -60,6 +60,8 @@ class Theme extends StatelessWidget {
   final bool isMaterialAppTheme;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   static final ThemeData _kFallbackTheme = new ThemeData.fallback();
@@ -219,6 +221,8 @@ class AnimatedTheme extends ImplicitlyAnimatedWidget {
   final bool isMaterialAppTheme;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override

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

@@ -78,6 +78,8 @@ class Tooltip extends StatefulWidget {
   final bool preferBelow;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override

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

@@ -31,6 +31,8 @@ class AutomaticKeepAlive extends StatefulWidget {
   }) : super(key: key);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override

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

@@ -254,6 +254,8 @@ class Banner extends StatelessWidget {
        super(key: key);
 
   /// The widget to show behind the banner.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// The message to show in the banner.
@@ -332,6 +334,8 @@ class CheckedModeBanner extends StatelessWidget {
   }) : super(key: key);
 
   /// The widget to show behind the banner.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override

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

@@ -2993,6 +2993,8 @@ class PositionedDirectional extends StatelessWidget {
   final double height;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override
@@ -5022,6 +5024,8 @@ class KeyedSubtree extends StatelessWidget {
        super(key: key);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// Creates a KeyedSubtree for child with a key that's based on the child's existing key or childIndex.

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

@@ -723,6 +723,8 @@ class RenderObjectToWidgetAdapter<T extends RenderObject> extends RenderObjectWi
   }) : super(key: new GlobalObjectKey(container));
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// The [RenderObject] that is the parent of the [Element] created by this widget.

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

@@ -270,6 +270,8 @@ class Container extends StatelessWidget {
   /// container will expand to fill all available space in its parent, unless
   /// the parent provides unbounded constraints, in which case the container
   /// will attempt to be as small as possible.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// Align the [child] within the container.

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

@@ -88,6 +88,8 @@ class Dismissible extends StatefulWidget {
        super(key: key);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// A widget that is stacked behind the child. If secondaryBackground is also

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

@@ -116,6 +116,8 @@ class Draggable<T> extends StatefulWidget {
   ///
   /// To limit the number of simultaneous drags on multitouch devices, see
   /// [maxSimultaneousDrags].
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// The widget to display instead of [child] when one or more drags are under way.

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

@@ -68,6 +68,8 @@ class FocusScope extends StatefulWidget {
   final bool autofocus;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// Returns the [node] of the [FocusScope] that most tightly encloses the

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

@@ -42,7 +42,11 @@ class Form extends StatefulWidget {
     return scope?._formState;
   }
 
-  /// Root of the widget hierarchy that contains this form.
+  /// The widget below this widget in the tree.
+  ///
+  /// This is the root of the widget hierarchy that contains this form.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// If true, form fields will validate and update their error text

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

@@ -29,6 +29,14 @@ export 'package:flutter/rendering.dart' show RenderObject, RenderBox, debugDumpR
 // abstract class FrogJar extends RenderObjectWidget { }
 // abstract class FrogJarParentData extends ParentData { Size size; }
 
+// DOCUMENTATION TEMPLATES FOR THE WIDGET LIBRARY
+
+/// {@template flutter.widgets.child}
+/// This widget can only have one child. To lay out multiple children, let this
+/// widget's child be a widget such as [Row], [Column], or [Stack], which have a
+/// `children` property, and then provide the children to that widget.
+/// {@endtemplate}
+
 // KEYS
 
 /// A key that is only equal to itself.
@@ -1316,6 +1324,8 @@ abstract class ProxyWidget extends Widget {
   const ProxyWidget({ Key key, @required this.child }) : super(key: key);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 }
 
@@ -1597,6 +1607,8 @@ abstract class SingleChildRenderObjectWidget extends RenderObjectWidget {
   const SingleChildRenderObjectWidget({ Key key, this.child }) : super(key: key);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override

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

@@ -192,6 +192,8 @@ class GestureDetector extends StatelessWidget {
        super(key: key);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// A pointer that might cause a tap has contacted the screen at a particular
@@ -461,6 +463,8 @@ class RawGestureDetector extends StatefulWidget {
        super(key: key);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// The gestures that this widget will attempt to recognize.

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

@@ -101,6 +101,8 @@ class GridPaper extends StatelessWidget {
   final int subdivisions;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override

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

@@ -111,6 +111,8 @@ class Hero extends StatefulWidget {
   /// the subtrees of any other heroes in the application with the same [tag].
   /// Changes in scale and aspect ratio work well in hero animations, changes
   /// in layout or composition do not.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   // Returns a map of all of the heroes in context, indexed by hero tag.

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

@@ -389,6 +389,8 @@ class AnimatedContainer extends ImplicitlyAnimatedWidget {
   /// container will expand to fill all available space in its parent, unless
   /// the parent provides unbounded constraints, in which case the container
   /// will attempt to be as small as possible.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// Align the [child] within the container.
@@ -523,6 +525,8 @@ class AnimatedPadding extends ImplicitlyAnimatedWidget {
   final EdgeInsetsGeometry padding;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override
@@ -597,6 +601,8 @@ class AnimatedAlign extends ImplicitlyAnimatedWidget {
   final AlignmentGeometry alignment;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override
@@ -684,6 +690,8 @@ class AnimatedPositioned extends ImplicitlyAnimatedWidget {
        super(key: key, curve: curve, duration: duration);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// The offset of the child's left edge from the left of the stack.
@@ -805,6 +813,8 @@ class AnimatedPositionedDirectional extends ImplicitlyAnimatedWidget {
       super(key: key, curve: curve, duration: duration);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// The offset of the child's start edge from the start of the stack.
@@ -911,6 +921,8 @@ class AnimatedOpacity extends ImplicitlyAnimatedWidget {
        super(key: key, curve: curve, duration: duration);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// The target opacity.
@@ -978,6 +990,8 @@ class AnimatedDefaultTextStyle extends ImplicitlyAnimatedWidget {
        super(key: key, curve: curve, duration: duration);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// The target text style.
@@ -1088,6 +1102,8 @@ class AnimatedPhysicalModel extends ImplicitlyAnimatedWidget {
        super(key: key, curve: curve, duration: duration);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// The type of shape.

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

@@ -394,6 +394,8 @@ class Localizations extends StatefulWidget {
   final List<LocalizationsDelegate<dynamic>> delegates;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// The locale of the Localizations widget for the widget tree that

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

@@ -99,6 +99,8 @@ class NotificationListener<T extends Notification> extends StatelessWidget {
   /// The widget directly below this widget in the tree.
   ///
   /// This is not necessarily the widget that dispatched the notification.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// Called when a notification of the appropriate type arrives at this

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

@@ -86,7 +86,7 @@ class GlowingOverscrollIndicator extends StatefulWidget {
 
   /// The color of the glow. The alpha channel is ignored.
   final Color color;
-  
+
   /// A check that specifies whether a [ScrollNotification] should be
   /// handled by this widget.
   ///
@@ -94,9 +94,10 @@ class GlowingOverscrollIndicator extends StatefulWidget {
   /// else for more complicated layouts.
   final ScrollNotificationPredicate notificationPredicate;
 
-  /// The subtree to place inside the overscroll indicator. This should include
-  /// a source of [ScrollNotification] notifications, typically a [Scrollable]
-  /// widget.
+  /// The widget below this widget in the tree.
+  ///
+  /// The overscroll indicator will paint on top of this child. This child (and its
+  /// subtree) should include a source of [ScrollNotification] notifications.
   ///
   /// Typically a [GlowingOverscrollIndicator] is created by a
   /// [ScrollBehavior.buildViewportChrome] method, in which case

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

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

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

@@ -50,6 +50,8 @@ class PreferredSize extends StatelessWidget implements PreferredSizeWidget {
   }) : super(key: key);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override

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

@@ -44,6 +44,8 @@ class RawKeyboardListener extends StatefulWidget {
   final ValueChanged<RawKeyEvent> onKey;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override

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

@@ -58,6 +58,8 @@ class SafeArea extends StatelessWidget {
   ///
   /// The padding on the [MediaQuery] for the [child] will be suitably adjusted
   /// to zero out any sides that were avoided by this widget.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override

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

@@ -26,6 +26,8 @@ class SemanticsDebugger extends StatefulWidget {
   const SemanticsDebugger({ Key key, this.child }) : super(key: key);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override

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

@@ -112,6 +112,8 @@ class SingleChildScrollView extends StatelessWidget {
   final ScrollPhysics physics;
 
   /// The widget that scrolls.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   AxisDirection _getDirection(BuildContext context) {

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

@@ -34,6 +34,8 @@ class Title extends StatelessWidget {
   final Color color;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override

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

@@ -149,6 +149,8 @@ class SlideTransition extends AnimatedWidget {
   final bool transformHitTests;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override
@@ -191,6 +193,8 @@ class ScaleTransition extends AnimatedWidget {
   final Alignment alignment;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override
@@ -224,6 +228,8 @@ class RotationTransition extends AnimatedWidget {
   Animation<double> get turns => listenable;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override
@@ -269,6 +275,8 @@ class SizeTransition extends AnimatedWidget {
   final double axisAlignment;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override
@@ -312,6 +320,8 @@ class FadeTransition extends AnimatedWidget {
   Animation<double> get opacity => listenable;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override
@@ -362,6 +372,8 @@ class PositionedTransition extends AnimatedWidget {
   Animation<RelativeRect> get rect => listenable;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override
@@ -405,6 +417,8 @@ class RelativePositionedTransition extends AnimatedWidget {
   final Size size;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override
@@ -454,6 +468,8 @@ class DecoratedBoxTransition extends AnimatedWidget {
   final DecorationPosition position;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override
@@ -492,6 +508,8 @@ class AlignTransition extends AnimatedWidget {
   final double heightFactor;
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   @override
@@ -594,13 +612,15 @@ class AnimatedBuilder extends AnimatedWidget {
   /// Called every time the animation changes value.
   final TransitionBuilder builder;
 
-  /// If your builder function contains a subtree that does not depend on the
-  /// animation, it's more efficient to build that subtree once instead of
-  /// rebuilding it on every animation tick.
+  /// The child widget to pass to the [builder].
+  ///
+  /// If a [builder] callback's return value contains a subtree that does not
+  /// depend on the animation, it's more efficient to build that subtree once
+  /// instead of rebuilding it on every animation tick.
   ///
-  /// If you pass the pre-built subtree as the [child] parameter, the
-  /// AnimatedBuilder will pass it back to your builder function so that you
-  /// can incorporate it into your build.
+  /// If the pre-built subtree is passed as the [child] parameter, the
+  /// [AnimatedBuilder] will pass it back to the [builder] function so that it
+  /// can be incorporated into the build.
   ///
   /// Using this pre-built child is entirely optional, but can improve
   /// performance significantly in some cases and is therefore a good practice.

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

@@ -28,6 +28,8 @@ class WillPopScope extends StatefulWidget {
        super(key: key);
 
   /// The widget below this widget in the tree.
+  ///
+  /// {@macro flutter.widgets.child}
   final Widget child;
 
   /// Called to veto attempts by the user to dismiss the enclosing [ModalRoute].