Add dartdoc to basic.dart (#4345)

This patch starts working through the missing dartdocs in widgets.dart.

packages/flutter/lib/src/gestures/lsq_solver.dart

@@ -105,7 +105,7 @@ class PolynomialFit {
 class LeastSquaresSolver {
   /// Creates a least-squares solver.
   ///
-  /// The [x], [y], and [w] arguments must be non-null.
+  /// The [x], [y], and [w] arguments must not be null.
   LeastSquaresSolver(this.x, this.y, this.w) {
     assert(x.length == y.length);
     assert(y.length == w.length);

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

@@ -165,6 +165,7 @@ class DataCell {
     this.onTap
   });
 
+  /// A cell that has no content and has zero width and height.
   static final DataCell empty = new DataCell(new Container(width: 0.0, height: 0.0));
 
   /// The data for the row.

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

@@ -37,15 +37,19 @@ class Dialog extends StatelessWidget {
   /// of the dialog.
   final Widget title;
 
-  // Padding around the title; uses material design default if none is supplied
-  // If there is no title, no padding will be provided
+  /// Padding around the title.
+  ///
+  /// Uses material design default if none is supplied. If there is no title, no
+  /// padding will be provided.
   final EdgeInsets titlePadding;
 
   /// The (optional) content of the dialog is displayed in the center of the
   /// dialog in a lighter font.
   final Widget content;
 
-  // Padding around the content; uses material design default if none is supplied
+  /// Padding around the content.
+  ///
+  /// Uses material design default if none is supplied.
   final EdgeInsets contentPadding;
 
   /// The (optional) set of actions that are displayed at the bottom of the

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

@@ -31,7 +31,7 @@ import 'theme.dart';
 class Icon extends StatelessWidget {
   /// Creates an icon.
   ///
-  /// The size argument is required to be non-null.
+  /// The [size] argument most not be null.
   Icon({
     Key key,
     this.icon,

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

@@ -3,6 +3,7 @@
 // found in the LICENSE file.
 
 import 'package:flutter/widgets.dart';
+import 'package:meta/meta.dart';
 
 import 'icon_theme_data.dart';
 
@@ -10,10 +11,10 @@ import 'icon_theme_data.dart';
 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.
+  /// Both [data] and [child] arguments must not be null.
   IconTheme({
     Key key,
-    this.data,
+    @required this.data,
     Widget child
   }) : super(key: key, child: child) {
     assert(data != null);

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

@@ -159,14 +159,14 @@ abstract class MaterialInkController {
 class Material extends StatefulWidget {
   /// Creates a piece of material.
   ///
-  /// Both the type and the elevation arguments are required.
+  /// The [type] and the [elevation] arguments must not be null.
   Material({
     Key key,
-    this.child,
     this.type: MaterialType.canvas,
     this.elevation: 0,
     this.color,
-    this.textStyle
+    this.textStyle,
+    this.child
   }) : super(key: key) {
     assert(type != null);
     assert(elevation != null);

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

@@ -5,6 +5,7 @@
 import 'dart:async';
 
 import 'package:flutter/widgets.dart';
+import 'package:meta/meta.dart';
 
 import 'constants.dart';
 import 'divider.dart';
@@ -453,9 +454,12 @@ typedef List<PopupMenuEntry<T>> PopupMenuItemBuilder<T>(BuildContext context);
 /// the selected menu item. If child is null then a standard 'navigation/more_vert'
 /// icon is created.
 class PopupMenuButton<T> extends StatefulWidget {
+  /// Creates a button that shows a popup menu.
+  ///
+  /// The [itemBuilder] argument must not be null.
   PopupMenuButton({
     Key key,
-    this.itemBuilder,
+    @required this.itemBuilder,
     this.initialValue,
     this.onSelected,
     this.tooltip: 'Show menu',

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

@@ -744,6 +744,8 @@ class ScaffoldFeatureController<T extends Widget, U> {
   const ScaffoldFeatureController._(this._widget, this._completer, this.close, this.setState);
   final T _widget;
   final Completer<U> _completer;
+
+  /// Completes when the feature controlled by this object is no longer visible.
   Future<U> get closed => _completer.future;
 
   /// Remove the feature (e.g., bottom sheet or snack bar) from the scaffold.

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

@@ -3,6 +3,7 @@
 // found in the LICENSE file.
 
 import 'package:flutter/widgets.dart';
+import 'package:meta/meta.dart';
 
 import 'theme_data.dart';
 
@@ -20,10 +21,10 @@ const Duration kThemeAnimationDuration = const Duration(milliseconds: 200);
 class Theme extends InheritedWidget {
   /// Applies the given theme [data] to [child].
   ///
-  /// Both [child] and [data] must be non-null.
+  /// The [data] and [child] arguments must not be null.
   Theme({
     Key key,
-    this.data,
+    @required this.data,
     Widget child
   }) : super(key: key, child: child) {
     assert(child != null);
@@ -71,11 +72,11 @@ class ThemeDataTween extends Tween<ThemeData> {
 class AnimatedTheme extends ImplicitlyAnimatedWidget {
   /// Creates an animated theme.
   ///
-  /// By default, the theme transition uses a linear curve. Both [data] and
-  /// [child] are required.
+  /// By default, the theme transition uses a linear curve. The [data] and
+  /// [child] arguments must not be null.
   AnimatedTheme({
     Key key,
-    this.data,
+    @required this.data,
     Curve curve: Curves.linear,
     Duration duration: kThemeAnimationDuration,
     this.child

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

@@ -147,7 +147,7 @@ abstract class AutoLayoutDelegate {
   bool shouldUpdateConstraints(AutoLayoutDelegate oldDelegate);
 }
 
-/// Uses the cassowary constraint solver to automatically size and position children.
+/// A render object that uses the cassowary constraint solver to automatically size and position children.
 class RenderAutoLayout extends RenderBox
     with ContainerRenderObjectMixin<RenderBox, AutoLayoutParentData>,
          RenderBoxContainerDefaultsMixin<RenderBox, AutoLayoutParentData> {

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

@@ -5,6 +5,8 @@
 import 'dart:math' as math;
 import 'dart:typed_data';
 
+import 'package:meta/meta.dart';
+
 import 'box.dart';
 import 'object.dart';
 import 'viewport.dart';
@@ -170,6 +172,11 @@ abstract class GridDelegate {
   GridSpecification getGridSpecification(BoxConstraints constraints, int childCount);
 
   /// Override this function to control where children are placed in the grid.
+  ///
+  /// During layout, the grid calls this function for each child, passing the
+  /// [placementData] associated with that child as context. The returned
+  /// [GridChildPlacement] is then used to determine the size and position of
+  /// that child within the grid.
   GridChildPlacement getChildPlacement(GridSpecification specification, int index, Object placementData);
 
   /// Override this method to return true when the children need to be laid out.
@@ -301,7 +308,7 @@ class FixedColumnCountGridDelegate extends GridDelegateWithInOrderChildPlacement
   ///
   /// The [columnCount] argument must not be null.
   FixedColumnCountGridDelegate({
-    this.columnCount,
+    @required this.columnCount,
     double columnSpacing: 0.0,
     double rowSpacing: 0.0,
     EdgeInsets padding: EdgeInsets.zero,
@@ -378,7 +385,7 @@ class MaxTileWidthGridDelegate extends GridDelegateWithInOrderChildPlacement {
   ///
   /// The [maxTileWidth] argument must not be null.
   MaxTileWidthGridDelegate({
-    this.maxTileWidth,
+    @required this.maxTileWidth,
     this.tileAspectRatio: 1.0,
     double columnSpacing: 0.0,
     double rowSpacing: 0.0,
@@ -447,7 +454,7 @@ class MaxTileWidthGridDelegate extends GridDelegateWithInOrderChildPlacement {
 
 /// Parent data for use with [RenderGrid]
 class GridParentData extends ContainerBoxParentDataMixin<RenderBox> {
-  /// Opaque data passed to the getChildPlacement method of the grid's [GridDelegate].
+  /// Opaque data passed to the [GridDelegate.getChildPlacement] method of the grid's [GridDelegate].
   Object placementData;
 
   @override

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

@@ -1093,8 +1093,8 @@ enum DecorationPosition {
 class RenderDecoratedBox extends RenderProxyBox {
   /// Creates a decorated box.
   ///
-  /// Both the [decoration] and the [position] arguments are required. By
-  /// default the decoration paints behind the child.
+  /// The [decoration] and [position] arguments must not be null. By default the
+  /// decoration paints behind the child.
   RenderDecoratedBox({
     Decoration decoration,
     DecorationPosition position: DecorationPosition.background,

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

@@ -856,7 +856,7 @@ class RenderCustomSingleChildLayoutBox extends RenderShiftedBox {
 class RenderBaseline extends RenderShiftedBox {
   /// Creates a [RenderBaseline] object.
   ///
-  /// The [baseline] and [baselineType] arguments are required.
+  /// The [baseline] and [baselineType] arguments must not be null.
   RenderBaseline({
     RenderBox child,
     double baseline,

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

@@ -193,10 +193,10 @@ typedef Offset ViewportDimensionsChangeCallback(ViewportDimensions dimensions);
 
 /// A render object that's bigger on the inside.
 ///
-/// The child of a viewport can layout to a larger size than the viewport
-/// itself. If that happens, only a portion of the child will be visible through
-/// the viewport. The portion of the child that is visible can be controlled
-/// with the [paintOffset].
+/// The child of a viewport can layout to a larger size along the viewport's
+/// [mainAxis] than the viewport itself. If that happens, only a portion of the
+/// child will be visible through the viewport. The portion of the child that is
+/// visible can be controlled with the [paintOffset].
 ///
 /// See also:
 ///
@@ -334,10 +334,10 @@ class RenderViewport extends RenderViewportBase with RenderObjectWithChildMixin<
 
 /// A render object that shows a subset of its children.
 ///
-/// The children of a viewport can layout to a larger size than the viewport
-/// itself. If that happens, only a subset of the children will be visible
-/// through the viewport. The subset of children that are visible can be
-/// controlled with the [paintOffset].
+/// The children of a viewport can layout to a larger size along the viewport's
+/// [mainAxis] than the viewport itself. If that happens, only a subset of the
+/// children will be visible through the viewport. The subset of children that
+/// are visible can be controlled with the [paintOffset].
 ///
 /// See also:
 ///

packages/flutter/lib/src/services/image_cache.dart

@@ -142,6 +142,7 @@ class ImageCache {
   /// cache, then the [ImageResource] object is immediately usable and the
   /// provider is not called.
   ImageResource loadProvider(ImageProvider provider) {
+    assert(provider != null);
     ImageResource result = _cache[provider];
     if (result != null) {
       _cache.remove(provider);

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

@@ -7,6 +7,7 @@ import 'dart:ui' as ui show window;
 
 import 'package:flutter/rendering.dart';
 import 'package:flutter/services.dart';
+import 'package:meta/meta.dart';
 
 import 'asset_vendor.dart';
 import 'banner.dart';
@@ -20,6 +21,7 @@ import 'performance_overlay.dart';
 import 'semantics_debugger.dart';
 import 'title.dart';
 
+/// Signature for a function that is called when the operating system changes the current locale.
 typedef Future<LocaleQueryData> LocaleChangedCallback(Locale locale);
 
 /// A convenience class that wraps a number of widgets that are commonly
@@ -32,13 +34,15 @@ typedef Future<LocaleQueryData> LocaleChangedCallback(Locale locale);
 /// The [onGenerateRoute] argument is required, and corresponds to
 /// [Navigator.onGenerateRoute].
 class WidgetsApp extends StatefulWidget {
+  /// Creates a widget that wraps a number of widgets that are commonly
+  /// required for an application.
   WidgetsApp({
     Key key,
+    @required this.onGenerateRoute,
     this.title,
     this.textStyle,
     this.color,
     this.navigatorObserver,
-    this.onGenerateRoute,
     this.onLocaleChanged,
     this.showPerformanceOverlay: false,
     this.showSemanticsDebugger: false,
@@ -96,16 +100,17 @@ class WidgetsApp extends StatefulWidget {
   /// The observer for the Navigator created for this app.
   final NavigatorObserver navigatorObserver;
 
+  /// If true, forces the performance overlay to be visible in all instances.
+  ///
+  /// Used by `showPerformanceOverlay` observatory extension.
   static bool showPerformanceOverlayOverride = false;
 
   @override
-  WidgetsAppState<WidgetsApp> createState() => new WidgetsAppState<WidgetsApp>();
+  _WidgetsAppState createState() => new _WidgetsAppState();
 }
 
-class WidgetsAppState<T extends WidgetsApp> extends State<T> implements WidgetsBindingObserver {
-
+class _WidgetsAppState extends State<WidgetsApp> implements WidgetsBindingObserver {
   GlobalObjectKey _navigator;
-
   LocaleQueryData _localeData;
 
   @override

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

@@ -8,6 +8,7 @@ import 'dart:convert';
 import 'dart:ui' as ui show Image;
 
 import 'package:flutter/services.dart';
+import 'package:meta/meta.dart';
 import 'package:mojo/core.dart' as core;
 
 import 'media_query.dart';
@@ -26,8 +27,11 @@ abstract class _AssetResolver { // ignore: one_member_abstracts
 // Wraps an underlying [AssetBundle] and forwards calls after resolving the
 // asset key.
 class _ResolvingAssetBundle extends CachingAssetBundle {
+  _ResolvingAssetBundle({ this.bundle, this.resolver }) {
+    assert(bundle != null);
+    assert(resolver != null);
+  }
 
-  _ResolvingAssetBundle({ this.bundle, this.resolver });
   final AssetBundle bundle;
   final _AssetResolver resolver;
 
@@ -197,23 +201,29 @@ class _ResolutionAwareAssetResolver extends _VariantAssetResolver {
 /// icons/2.0x/heart.png
 /// ```
 class AssetVendor extends StatefulWidget {
+  /// Creates a widget that establishes an asset resolution strategy for its descendants.
   AssetVendor({
     Key key,
-    this.bundle,
+    @required this.bundle,
     this.devicePixelRatio,
-    this.child,
-    this.imageDecoder: decodeImageFromDataPipe
-  }) : super(key: key);
+    this.imageDecoder: decodeImageFromDataPipe,
+    this.child
+  }) : super(key: key) {
+    assert(bundle != null);
+  }
 
+  /// The bundle from which to load the assets.
   final AssetBundle bundle;
 
+  /// If non-null, the device pixel ratio to assume when selecting assets.
   final double devicePixelRatio;
 
+  /// The function to use for decoding images.
+  final ImageDecoder imageDecoder;
+
   /// The widget below this widget in the tree.
   final Widget child;
 
-  final ImageDecoder imageDecoder;
-
   @override
   _AssetVendorState createState() => new _AssetVendorState();
 

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

@@ -3,6 +3,7 @@
 // found in the LICENSE file.
 
 import 'package:flutter/rendering.dart';
+import 'package:meta/meta.dart';
 
 import 'framework.dart';
 
@@ -10,13 +11,18 @@ export 'package:flutter/rendering.dart' show
     AutoLayoutRect,
     AutoLayoutDelegate;
 
+/// A widget that uses the cassowary constraint solver to automatically size and position children.
 class AutoLayout extends MultiChildRenderObjectWidget {
+  /// Creates a widget that uses the cassowary constraint solver to automatically size and position children.
   AutoLayout({
     Key key,
     this.delegate,
     List<Widget> children: const <Widget>[]
   }) : super(key: key, children: children);
 
+  /// The delegate that generates constraints for the layout.
+  ///
+  /// If the delgate is null, the layout is unconstrained.
   final AutoLayoutDelegate delegate;
 
   @override
@@ -28,10 +34,29 @@ class AutoLayout extends MultiChildRenderObjectWidget {
   }
 }
 
+/// A widget that provides constraints for a child of an [AutoLayout] widget.
+///
+/// An [AutoLayoutChild] widget must be a descendant of an [AutoLayout], and
+/// the path from the [AutoLayoutChild] widget to its enclosing [AutoLayout]
+/// must contain only [StatelessWidget]s or [StatefulWidget]s (not other kinds
+/// of widgets, like [RenderObjectWidget]s).
 class AutoLayoutChild extends ParentDataWidget<AutoLayout> {
-  AutoLayoutChild({ AutoLayoutRect rect, Widget child })
-    : rect = rect, super(key: new ObjectKey(rect), child: child);
+  /// Creates a widget that provides constraints for a child of an [AutoLayout] widget.
+  ///
+  /// The object identity of the [rect] argument must be unique among children
+  /// of a given [AutoLayout] widget.
+  AutoLayoutChild({
+    AutoLayoutRect rect,
+    @required Widget child
+  }) : rect = rect,
+       super(key: rect != null ? new ObjectKey(rect) : null, child: child);
 
+  /// The constraints to use for this child.
+  ///
+  /// The object identity of the [rect] object must be unique among children of
+  /// a given [AutoLayout] widget.
+  ///
+  /// If null, the child's size and position are unconstrained.
   final AutoLayoutRect rect;
 
   @override

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

@@ -4,6 +4,8 @@
 
 import 'dart:math' as math;
 
+import 'package:meta/meta.dart';
+
 import 'basic.dart';
 import 'framework.dart';
 
@@ -37,10 +39,10 @@ enum BannerLocation {
 class BannerPainter extends CustomPainter {
   /// Creates a banner painter.
   ///
-  /// The message and location arguments are required.
+  /// The [message] and [location] arguments must not be null.
   const BannerPainter({
-    this.message,
-    this.location
+    @required this.message,
+    @required this.location
   });
 
   /// The message to show in the banner.
@@ -124,7 +126,7 @@ class BannerPainter extends CustomPainter {
 class Banner extends StatelessWidget {
   /// Creates a banner.
   ///
-  /// The message and location arguments are required.
+  /// The [message] and [location] arguments must not be null.
   Banner({
     Key key,
     this.child,

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

@@ -53,7 +53,7 @@ export 'package:flutter/rendering.dart' show
 
 // PAINTING NODES
 
-/// Makes its child partially transparent.
+/// A widget that makes its child partially transparent.
 ///
 /// This class paints its child into an intermediate buffer and then blends the
 /// child back into the scene partially transparent.
@@ -63,8 +63,15 @@ export 'package:flutter/rendering.dart' show
 /// buffer. For the value 0.0, the child is simply not painted at all. For the
 /// value 1.0, the child is painted immediately without an intermediate buffer.
 class Opacity extends SingleChildRenderObjectWidget {
-  Opacity({ Key key, this.opacity, Widget child })
-    : super(key: key, child: child) {
+  /// Creates a widget that makes its child partially transparent.
+  ///
+  /// The [opacity] argument must not be null and must be between 0.0 and 1.0
+  /// (inclusive).
+  Opacity({
+    Key key,
+    @required this.opacity,
+    Widget child
+  }) : super(key: key, child: child) {
     assert(opacity != null && opacity >= 0.0 && opacity <= 1.0);
   }
 
@@ -95,7 +102,7 @@ class Opacity extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Applies a mask generated by a [Shader] to its child.
+/// A widget that applies a mask generated by a [Shader] to its child.
 ///
 /// For example, [ShaderMask] can be used to gradually fade out the edge
 /// of a child by using a [ui.Gradient.linear] mask.
@@ -105,7 +112,7 @@ class ShaderMask extends SingleChildRenderObjectWidget {
   /// The [shaderCallback] and [transferMode] arguments must not be null.
   ShaderMask({
     Key key,
-    this.shaderCallback,
+    @required this.shaderCallback,
     this.transferMode: TransferMode.modulate,
     Widget child
   }) : super(key: key, child: child) {
@@ -141,7 +148,7 @@ class ShaderMask extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Applies a filter to the existing painted content and then paints [child].
+/// A widget that applies a filter to the existing painted content and then paints [child].
 ///
 /// This effect is relatively expensive, especially if the filter is non-local,
 /// such as a blur.
@@ -151,7 +158,7 @@ class BackdropFilter extends SingleChildRenderObjectWidget {
   /// The [filter] argument must not be null.
   BackdropFilter({
     Key key,
-    this.filter,
+    @required this.filter,
     Widget child
   }) : super(key: key, child: child) {
     assert(filter != null);
@@ -174,14 +181,20 @@ class BackdropFilter extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Paints a [Decoration] either before or after its child paints.
-/// Container insets its child by the widths of the borders, this Widget does not.
+/// A widget that paints a [Decoration] either before or after its child paints.
+///
+/// [Container] insets its child by the widths of the borders; this widget does
+/// not.
 ///
 /// Commonly used with [BoxDecoration].
 class DecoratedBox extends SingleChildRenderObjectWidget {
+  /// Creates a widget that paints a [Decoration].
+  ///
+  /// The [decoration] and [position] arguments must not be null. By default the
+  /// decoration paints behind the child.
   DecoratedBox({
     Key key,
-    this.decoration,
+    @required this.decoration,
     this.position: DecorationPosition.background,
     Widget child
   }) : super(key: key, child: child) {
@@ -208,7 +221,7 @@ class DecoratedBox extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Provides a canvas on which to draw during the paint phase.
+/// A widget that provides a canvas on which to draw during the paint phase.
 ///
 /// When asked to paint, [CustomPaint] first asks its [painter] to paint on the
 /// current canvas, then it paints its child, and then, after painting its
@@ -261,7 +274,7 @@ class CustomPaint extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Clips its child using a rectangle.
+/// A widget that clips its child using a rectangle.
 ///
 /// By default, [ClipRect] prevents its child from painting outside its
 /// bounds, but the size and location of the clip rect can be customized using a
@@ -290,7 +303,7 @@ class ClipRect extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Clips its child using a rounded rectangle.
+/// A widget that clips its child using a rounded rectangle.
 ///
 /// Creates a rounded rectangle from its layout dimensions and the given x and
 /// y radius values and prevents its child from painting outside that rounded
@@ -323,7 +336,7 @@ class ClipRRect extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Clips its child using an oval.
+/// A widget that clips its child using an oval.
 ///
 /// By default, inscribes an axis-aligned oval into its layout dimensions and
 /// prevents its child from painting outside that oval, but the size and
@@ -360,7 +373,7 @@ class ClipOval extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Clips its child using a path.
+/// A widget that clips its child using a path.
 ///
 /// Calls a callback on a delegate whenever the widget is to be
 /// painted. The callback returns a path and the widget prevents the
@@ -405,14 +418,14 @@ class ClipPath extends SingleChildRenderObjectWidget {
 
 // POSITIONING AND SIZING NODES
 
-/// Applies a transformation before painting its child.
+/// A widget that applies a transformation before painting its child.
 class Transform extends SingleChildRenderObjectWidget {
   /// Creates a widget that transforms its child.
   ///
   /// The [transform] argument must not be null.
   Transform({
     Key key,
-    this.transform,
+    @required this.transform,
     this.origin,
     this.alignment,
     this.transformHitTests: true,
@@ -458,15 +471,15 @@ class Transform extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Applies a translation expressed as a fraction of the box's size before
-/// painting its child.
+/// A widget that applies a translation expressed as a fraction of the box's
+/// size before painting its child.
 class FractionalTranslation extends SingleChildRenderObjectWidget {
   /// Creates a widget that translates its child's painting.
   ///
   /// The [translation] argument must not be null.
   FractionalTranslation({
     Key key,
-    this.translation,
+    @required this.translation,
     this.transformHitTests: true,
     Widget child
   }) : super(key: key, child: child) {
@@ -490,14 +503,20 @@ class FractionalTranslation extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Rotates its child by a integral number of quarter turns.
+/// A widget that rotates its child by a integral number of quarter turns.
 ///
 /// Unlike [Transform], which applies a transform just prior to painting,
 /// this object applies its rotation prior to layout, which means the entire
 /// rotated box consumes only as much space as required by the rotated child.
 class RotatedBox extends SingleChildRenderObjectWidget {
-  RotatedBox({ Key key, this.quarterTurns, Widget child })
-    : super(key: key, child: child) {
+  /// A widget that rotates its child.
+  ///
+  /// The [quarterTurns] argument must not be null.
+  RotatedBox({
+    Key key,
+    @required this.quarterTurns,
+    Widget child
+  }) : super(key: key, child: child) {
     assert(quarterTurns != null);
   }
 
@@ -513,15 +532,21 @@ class RotatedBox extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Insets its child by the given padding.
+/// A widget that insets its child by the given padding.
 ///
 /// When passing layout constraints to its child, padding shrinks the
 /// constraints by the given padding, causing the child to layout at a smaller
 /// size. Padding then sizes itself to its child's size, inflated by the
 /// padding, effectively creating empty space around the child.
 class Padding extends SingleChildRenderObjectWidget {
-  Padding({ Key key, this.padding, Widget child })
-    : super(key: key, child: child) {
+  /// Creates a widget that insets its child.
+  ///
+  /// The [padding] argument must not be null.
+  Padding({
+    Key key,
+    @required this.padding,
+    Widget child
+  }) : super(key: key, child: child) {
     assert(padding != null);
   }
 
@@ -537,8 +562,8 @@ class Padding extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Aligns its child within itself and optionally sizes itself based on the
-/// child's size.
+/// A widget that aligns its child within itself and optionally sizes itself
+/// based on the child's size.
 ///
 /// For example, to align a box at the bottom right, you would pass this box a
 /// tight constraint that is bigger than the child's natural size,
@@ -618,17 +643,18 @@ class Align extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Centers its child within itself.
+/// A widget that centers its child within itself.
 ///
 /// See also:
 ///
 ///  * [Align]
 class Center extends Align {
+  /// Creates a widget that centers its child.
   Center({ Key key, double widthFactor, double heightFactor, Widget child })
     : super(key: key, widthFactor: widthFactor, heightFactor: heightFactor, child: child);
 }
 
-/// Defers the layout of its single child to a delegate.
+/// A widget that defers the layout of its single child to a delegate.
 ///
 /// The delegate can determine the layout constraints for the child and can
 /// decide where to position the child. The delegate can also determine the size
@@ -647,10 +673,10 @@ class Center extends Align {
 class CustomSingleChildLayout extends SingleChildRenderObjectWidget {
   /// Creates a custom single child layout.
   ///
-  /// The delegate argument must not be null.
+  /// The [delegate] argument must not be null.
   CustomSingleChildLayout({
     Key key,
-    this.delegate,
+    @required this.delegate,
     Widget child
   }) : super(key: key, child: child) {
     assert(delegate != null);
@@ -669,6 +695,7 @@ class CustomSingleChildLayout extends SingleChildRenderObjectWidget {
 }
 
 /// Meta data for identifying children in a [CustomMultiChildLayout].
+///
 /// The [MultiChildLayoutDelegate] hasChild, layoutChild, and positionChild
 /// methods use these identifiers.
 class LayoutId extends ParentDataWidget<CustomMultiChildLayout> {
@@ -677,8 +704,8 @@ class LayoutId extends ParentDataWidget<CustomMultiChildLayout> {
   /// Both the child and the id arguments must not be null.
   LayoutId({
     Key key,
-    Widget child,
-    Object id
+    @required Object id,
+    @required Widget child
   }) : id = id, super(key: key ?? new ValueKey<Object>(id), child: child) {
     assert(child != null);
     assert(id != null);
@@ -708,7 +735,7 @@ class LayoutId extends ParentDataWidget<CustomMultiChildLayout> {
 
 const List<Widget> _emptyWidgetList = const <Widget>[];
 
-/// Defers the layout of multiple children to a delegate.
+/// A widget that defers the layout of multiple children to a delegate.
 ///
 /// The delegate can determine the layout constraints for each child and can
 /// decide where to position each child. The delegate can also determine the
@@ -724,11 +751,11 @@ const List<Widget> _emptyWidgetList = const <Widget>[];
 class CustomMultiChildLayout extends MultiChildRenderObjectWidget {
   /// Creates a custom multi-child layout.
   ///
-  /// The delegate argument must not be null.
+  /// The [delegate] argument must not be null.
   CustomMultiChildLayout({
     Key key,
-    List<Widget> children: _emptyWidgetList,
-    this.delegate
+    @required this.delegate,
+    List<Widget> children: _emptyWidgetList
   }) : super(key: key, children: children) {
     assert(delegate != null);
   }
@@ -757,6 +784,7 @@ class CustomMultiChildLayout extends MultiChildRenderObjectWidget {
 /// If not given a child, this widget will size itself to the given width and
 /// height, treating nulls as zero.
 class SizedBox extends SingleChildRenderObjectWidget {
+  /// Creates a box of a specific size.
   SizedBox({ Key key, this.width, this.height, Widget child })
     : super(key: key, child: child);
 
@@ -790,14 +818,20 @@ class SizedBox extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Imposes additional constraints on its child.
+/// A widget that imposes additional constraints on its child.
 ///
 /// For example, if you wanted [child] to have a minimum height of 50.0 logical
 /// pixels, you could use `const BoxConstraints(minHeight: 50.0)`` as the
 /// [additionalConstraints].
 class ConstrainedBox extends SingleChildRenderObjectWidget {
-  ConstrainedBox({ Key key, this.constraints, Widget child })
-    : super(key: key, child: child) {
+  /// Creates a widget that imposes additional constraints on its child.
+  ///
+  /// The [constraints] argument must not be null.
+  ConstrainedBox({
+    Key key,
+    @required this.constraints,
+    Widget child
+  }) : super(key: key, child: child) {
     assert(constraints != null);
   }
 
@@ -819,10 +853,11 @@ class ConstrainedBox extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Sizes its child to a fraction of the total available space.
+/// A widget that sizes its child to a fraction of the total available space.
 /// For more details about the layout algorithm, see [RenderFractionallySizedOverflowBox].
 ///
 /// See also:
+///
 /// * [Align] (which sizes itself based on its child's size and positions
 ///   the child according to a [FractionalOffset] value)
 /// * [OverflowBox]
@@ -904,8 +939,16 @@ class FractionallySizedBox extends SingleChildRenderObjectWidget {
 /// limited to maxWidth. Similarly, if this widget's maximum height is unconstrained
 /// then its child's height is limited to to maxHeight.
 class LimitedBox extends SingleChildRenderObjectWidget {
-  LimitedBox({ Key key, this.maxWidth: double.INFINITY, this.maxHeight: double.INFINITY, Widget child })
-    : super(key: key, child: child) {
+  /// Creates a box that limits its size only when it's unconstrained.
+  ///
+  /// The [maxWidth] and [maxHeight] arguments must not be null and must not be
+  /// negative.
+  LimitedBox({
+    Key key,
+    this.maxWidth: double.INFINITY,
+    this.maxHeight: double.INFINITY,
+    Widget child
+  }) : super(key: key, child: child) {
     assert(maxWidth != null && maxWidth >= 0.0);
     assert(maxHeight != null && maxHeight >= 0.0);
   }
@@ -1021,13 +1064,14 @@ class OverflowBox extends SingleChildRenderObjectWidget {
 class SizedOverflowBox extends SingleChildRenderObjectWidget {
   /// Creates a widget of a given size that lets its child overflow.
   ///
-  /// The [requestedSize] argument must not be null.
+  /// The [size] argument must not be null.
   SizedOverflowBox({
     Key key,
+    @required this.size,
     this.alignment: FractionalOffset.center,
-    this.size,
     Widget child
   }) : super(key: key, child: child) {
+    assert(size != null);
     assert(alignment != null && alignment.dx != null && alignment.dy != null);
   }
 
@@ -1069,10 +1113,11 @@ class SizedOverflowBox extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Lays the child out as if it was in the tree, but without painting anything,
+/// A widget that lays the child out as if it was in the tree, but without painting anything,
 /// without making the child available for hit testing, and without taking any
 /// room in the parent.
 class OffStage extends SingleChildRenderObjectWidget {
+  /// Creates a widget that visually hides its child.
   OffStage({ Key key, Widget child })
     : super(key: key, child: child);
 
@@ -1080,7 +1125,7 @@ class OffStage extends SingleChildRenderObjectWidget {
   RenderOffStage createRenderObject(BuildContext context) => new RenderOffStage();
 }
 
-/// Attempts to size the child to a specific aspect ratio.
+/// A widget that attempts to size the child to a specific aspect ratio.
 ///
 /// The widget first tries the largest width permited by the layout
 /// constraints. The height of the widget is determined by applying the
@@ -1107,8 +1152,14 @@ class OffStage extends SingleChildRenderObjectWidget {
 /// will eventually select a size for the child that meets the layout
 /// constraints but fails to meet the aspect ratio constraints.
 class AspectRatio extends SingleChildRenderObjectWidget {
-  AspectRatio({ Key key, this.aspectRatio, Widget child })
-    : super(key: key, child: child) {
+  /// Creates a widget with a specific aspect ratio.
+  ///
+  /// The [aspectRatio] argument must not be null.
+  AspectRatio({
+    Key key,
+    @required this.aspectRatio,
+    Widget child
+  }) : super(key: key, child: child) {
     assert(aspectRatio != null);
   }
 
@@ -1133,7 +1184,7 @@ class AspectRatio extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Sizes its child to the child's intrinsic width.
+/// A widget that sizes its child to the child's intrinsic width.
 ///
 /// Sizes its child's width to the child's maximum intrinsic width. If
 /// [stepWidth] is non-null, the child's width will be snapped to a multiple of
@@ -1146,6 +1197,9 @@ class AspectRatio extends SingleChildRenderObjectWidget {
 ///
 /// This class is relatively expensive. Avoid using it where possible.
 class IntrinsicWidth extends SingleChildRenderObjectWidget {
+  /// Creates a widget that sizes its child to the child's intrinsic width.
+  ///
+  /// This class is relatively expensive. Avoid using it where possible.
   IntrinsicWidth({ Key key, this.stepWidth, this.stepHeight, Widget child })
     : super(key: key, child: child);
 
@@ -1166,7 +1220,7 @@ class IntrinsicWidth extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Sizes its child to the child's intrinsic height.
+/// A widget that sizes its child to the child's intrinsic height.
 ///
 /// This class is useful, for example, when unlimited height is available and
 /// you would like a child that would otherwise attempt to expand infinitely to
@@ -1174,24 +1228,33 @@ class IntrinsicWidth extends SingleChildRenderObjectWidget {
 ///
 /// This class is relatively expensive. Avoid using it where possible.
 class IntrinsicHeight extends SingleChildRenderObjectWidget {
+  /// Creates a widget that sizes its child to the child's intrinsic height.
+  ///
+  /// This class is relatively expensive. Avoid using it where possible.
   IntrinsicHeight({ Key key, Widget child }) : super(key: key, child: child);
 
   @override
   RenderIntrinsicHeight createRenderObject(BuildContext context) => new RenderIntrinsicHeight();
 }
 
-/// Shifts the child down such that the child's baseline (or the
+/// A widget that positions its child according to the child's baseline.
+///
+/// This widget shifts the child down such that the child's baseline (or the
 /// bottom of the child, if the child has no baseline) is [baseline]
 /// logical pixels below the top of this box, then sizes this box to
 /// contain the child. If [baseline] is less than the distance from
 /// the top of the child to the baseline of the child, then the child
 /// is top-aligned instead.
 class Baseline extends SingleChildRenderObjectWidget {
-  /// Creates a [Baseline] object.
+  /// Creates a widget that positions its child according to the child's baseline.
   ///
-  /// The [baseline] and [baselineType] arguments are required.
-  Baseline({ Key key, this.baseline, this.baselineType, Widget child })
-    : super(key: key, child: child) {
+  /// The [baseline] and [baselineType] arguments must not be null.
+  Baseline({
+    Key key,
+    @required this.baseline,
+    @required this.baselineType,
+    Widget child
+  }) : super(key: key, child: child) {
     assert(baseline != null);
     assert(baselineType != null);
   }
@@ -1216,14 +1279,17 @@ class Baseline extends SingleChildRenderObjectWidget {
 
 /// A widget that's bigger on the inside.
 ///
-/// The child of a viewport can layout to a larger size than the viewport
-/// itself. If that happens, only a portion of the child will be visible through
-/// the viewport. The portion of the child that is visible is controlled by the
-/// scroll offset.
+/// The child of a viewport can layout to a larger size along the viewport's
+/// [mainAxis] than the viewport itself. If that happens, only a portion of the
+/// child will be visible through the viewport. The portion of the child that is
+/// visible is controlled by the scroll offset.
 ///
 /// Viewport is the core scrolling primitive in the system, but it can be used
 /// in other situations.
 class Viewport extends SingleChildRenderObjectWidget {
+  /// Creates a widget that's bigger on the inside.
+  ///
+  /// The [mainAxis] and [paintOffset] arguments must not be null.
   Viewport({
     Key key,
     this.paintOffset: Offset.zero,
@@ -1248,6 +1314,9 @@ class Viewport extends SingleChildRenderObjectWidget {
   /// is vertical).
   final Axis mainAxis;
 
+  /// The end of the viewport from which the paint offset is computed.
+  ///
+  /// See [ViewportAnchor] for more detail.
   final ViewportAnchor anchor;
 
   /// Called when the interior or exterior dimensions of the viewport change.
@@ -1277,19 +1346,32 @@ class Viewport extends SingleChildRenderObjectWidget {
 
 // CONTAINER
 
-/// A convenience widget that combines common painting, positioning, and sizing widgets.
+/// A convenience widget that combines common painting, positioning, and sizing
+/// widgets.
+///
+/// A container first surrounds the child with [padding] (inflated by any
+/// borders present in the [decoration]) and then applies additional
+/// [constraints] to the padded extent (incorporating the [width] and [height]
+/// as constraints, if either is non-null). The container is then surrounded by
+/// additional empty space described from the [margin].
+///
+/// During painting, the container first applies the given [transform], then
+/// paints the [decoration] to fill the padded extent, then it paints the child,
+/// and finally paints the [foregroundDecoration], also filling the padded
+/// extent.
 class Container extends StatelessWidget {
+  /// Creates a widget that combines common painting, positioning, and sizing widgets.
   Container({
     Key key,
-    this.child,
-    BoxConstraints constraints,
+    this.padding,
     this.decoration,
     this.foregroundDecoration,
+    double width,
+    double height,
+    BoxConstraints constraints,
     this.margin,
-    this.padding,
     this.transform,
-    double width,
-    double height
+    this.child
   }) : constraints =
         (width != null || height != null)
           ? constraints?.tighten(width: width, height: height)
@@ -1306,8 +1388,8 @@ class Container extends StatelessWidget {
   /// If null, the container will expand to fill all available space in its parent.
   final Widget child;
 
-  /// Additional constraints to apply to the child.
-  final BoxConstraints constraints;
+  /// Empty space to inscribe inside the decoration.
+  final EdgeInsets padding;
 
   /// The decoration to paint behind the child.
   final Decoration decoration;
@@ -1315,12 +1397,12 @@ class Container extends StatelessWidget {
   /// The decoration to paint in front of the child.
   final Decoration foregroundDecoration;
 
+  /// Additional constraints to apply to the child.
+  final BoxConstraints constraints;
+
   /// Empty space to surround the decoration.
   final EdgeInsets margin;
 
-  /// Empty space to inscribe inside the decoration.
-  final EdgeInsets padding;
-
   /// The transformation matrix to apply before painting the container.
   final Matrix4 transform;
 
@@ -1388,17 +1470,24 @@ class Container extends StatelessWidget {
 
 // LAYOUT NODES
 
-/// Uses the block layout algorithm for its children.
+/// A widget that uses the block layout algorithm for its children.
 ///
 /// This widget is rarely used directly. Instead, consider using [Block], which
 /// combines the block layout algorithm with scrolling behavior.
 ///
 /// For details about the block layout algorithm, see [RenderBlockBase].
+///
+/// See also:
+///
+///  * [Block] (which combines block layout with scrolling)
 class BlockBody extends MultiChildRenderObjectWidget {
+  /// Creates a block layout widget.
+  ///
+  /// By default, the [mainAxis] is [Axis.vertical].
   BlockBody({
     Key key,
-    List<Widget> children: _emptyWidgetList,
-    this.mainAxis: Axis.vertical
+    this.mainAxis: Axis.vertical,
+    List<Widget> children: _emptyWidgetList
   }) : super(key: key, children: children) {
     assert(mainAxis != null);
   }
@@ -1415,7 +1504,7 @@ class BlockBody extends MultiChildRenderObjectWidget {
   }
 }
 
-/// Uses the stack layout algorithm for its children.
+/// A widget that uses the stack layout algorithm for its children.
 ///
 /// This class is useful if you want to overlap several children in a
 /// simple way, for example having some text and an image, overlaid
@@ -1439,14 +1528,14 @@ class BlockBody extends MultiChildRenderObjectWidget {
 ///  * [CustomSingleChildLayout]
 ///  * [CustomMultiChildLayout]
 class Stack extends MultiChildRenderObjectWidget {
-  /// Creates a stack widget.
+  /// Creates a stack layout widget.
   ///
   /// By default, the non-positioned children of the stack are aligned by their
   /// top left corners.
   Stack({
     Key key,
-    List<Widget> children: _emptyWidgetList,
-    this.alignment: FractionalOffset.topLeft
+    this.alignment: FractionalOffset.topLeft,
+    List<Widget> children: _emptyWidgetList
   }) : super(key: key, children: children);
 
   /// How to align the non-positioned children in the stack.
@@ -1468,14 +1557,14 @@ class Stack extends MultiChildRenderObjectWidget {
 
 /// A [Stack] that shows a single child from a list of children.
 class IndexedStack extends Stack {
-  /// Creates a stack widget that paints a single child.
+  /// Creates a [Stack] widget that paints a single child.
   ///
   /// The [index] argument must not be null.
   IndexedStack({
     Key key,
-    List<Widget> children: _emptyWidgetList,
     FractionalOffset alignment: FractionalOffset.topLeft,
-    this.index: 0
+    this.index: 0,
+    List<Widget> children: _emptyWidgetList
   }) : super(key: key, alignment: alignment, children: children) {
     assert(index != null);
   }
@@ -1494,13 +1583,14 @@ class IndexedStack extends Stack {
   }
 }
 
-/// Controls where a child of a [Stack] is positioned.
+/// A widget that controls where a child of a [Stack] is positioned.
 ///
-/// This widget must be a descendant of a [Stack], and the path from this widget
-/// to its enclosing [Stack] must contain only [StatelessWidget]s or
-/// [StatefulWidget]s (not other kinds of widgets, like [RenderObjectWidget]s).
+/// A [Positioned] widget must be a descendant of a [Stack], and the path from
+/// the [Positioned] widget to its enclosing [Stack] must contain only
+/// [StatelessWidget]s or [StatefulWidget]s (not other kinds of widgets, like
+/// [RenderObjectWidget]s).
 class Positioned extends ParentDataWidget<Stack> {
-  /// Creates a Positioned object with the given values.
+  /// Creates a widget that controls where a child of a [Stack] is positioned.
   ///
   /// Only two out of the three horizontal values ([left], [right],
   /// [width]), and only two out of the three vertical values ([top],
@@ -1508,13 +1598,13 @@ class Positioned extends ParentDataWidget<Stack> {
   /// the three must be null.
   Positioned({
     Key key,
-    Widget child,
     this.left,
     this.top,
     this.right,
     this.bottom,
     this.width,
-    this.height
+    this.height,
+    @required Widget child
   }) : super(key: key, child: child) {
     assert(left == null || right == null || width == null);
     assert(top == null || bottom == null || height == null);
@@ -1634,8 +1724,17 @@ class Positioned extends ParentDataWidget<Stack> {
   }
 }
 
-abstract class GridRenderObjectWidgetBase extends MultiChildRenderObjectWidget {
-  GridRenderObjectWidgetBase({
+/// A [MultiChildRenderObjectWidget] for use with [RenderGrid].
+///
+/// Typically not used directly. Instead, consider using one of its subclasses,
+/// such as:
+///
+///  * [FixedColumnCountGrid] (which creates a grid with a fixed number of columns)
+///  * [MaxTileWidthGrid] (which creates a grid whose tiles have a maximum width)
+///  * [CustomGrid] (which lets you supply your own [GridDelegate])
+abstract class GridRenderObjectWidget extends MultiChildRenderObjectWidget {
+  /// Initializes fields for subclasses.
+  GridRenderObjectWidget({
     List<Widget> children: _emptyWidgetList,
     Key key
   }) : super(key: key, children: children) {
@@ -1656,12 +1755,21 @@ abstract class GridRenderObjectWidgetBase extends MultiChildRenderObjectWidget {
   }
 }
 
-/// Uses the grid layout algorithm for its children.
+/// A widget that creates a grid using a custom [delegate].
 ///
 /// For details about the grid layout algorithm, see [RenderGrid].
-class CustomGrid extends GridRenderObjectWidgetBase {
-  CustomGrid({ Key key, List<Widget> children: _emptyWidgetList, this.delegate })
-    : super(key: key, children: children) {
+///
+/// To pass data to your delegate's [GridDelegate.getChildPlacement] function,
+/// consider using [GridPlacementData].
+class CustomGrid extends GridRenderObjectWidget {
+  /// Creates a grid with a custom [delegate].
+  ///
+  /// The [delegate] argument must not be null.
+  CustomGrid({
+    Key key,
+    @required this.delegate,
+    List<Widget> children: _emptyWidgetList
+  }) : super(key: key, children: children) {
     assert(delegate != null);
   }
 
@@ -1672,20 +1780,24 @@ class CustomGrid extends GridRenderObjectWidgetBase {
   GridDelegate createDelegate() => delegate;
 }
 
-/// Uses a grid layout with a fixed column count.
+/// A widget that uses a grid layout with a fixed column count.
 ///
 /// For details about the grid layout algorithm, see [FixedColumnCountGridDelegate].
-class FixedColumnCountGrid extends GridRenderObjectWidgetBase {
+class FixedColumnCountGrid extends GridRenderObjectWidget {
+  /// Creates a grid with a fixed number of columns.
+  ///
+  /// The [columnCount] argument must not be negative.
   FixedColumnCountGrid({
     Key key,
-    List<Widget> children: _emptyWidgetList,
-    this.columnCount,
+    @required this.columnCount,
     this.columnSpacing: 0.0,
     this.rowSpacing: 0.0,
     this.tileAspectRatio: 1.0,
-    this.padding: EdgeInsets.zero
+    this.padding: EdgeInsets.zero,
+    List<Widget> children: _emptyWidgetList
   }) : super(key: key, children: children) {
-    assert(columnCount != null);
+    assert(columnCount != null && columnCount >= 0);
+    assert(tileAspectRatio != null && tileAspectRatio > 0.0);
   }
 
   /// The number of columns in the grid.
@@ -1715,20 +1827,24 @@ class FixedColumnCountGrid extends GridRenderObjectWidgetBase {
   }
 }
 
-/// Uses a grid layout with a max tile width.
+/// A widget that uses a grid layout with a maximum tile width.
 ///
 /// For details about the grid layout algorithm, see [MaxTileWidthGridDelegate].
-class MaxTileWidthGrid extends GridRenderObjectWidgetBase {
+class MaxTileWidthGrid extends GridRenderObjectWidget {
+  /// Creates a grid with a maximum tile width.
+  ///
+  /// The [columnCount] argument must not be negative.
   MaxTileWidthGrid({
     Key key,
-    List<Widget> children: _emptyWidgetList,
-    this.maxTileWidth,
+    @required this.maxTileWidth,
     this.columnSpacing: 0.0,
     this.rowSpacing: 0.0,
     this.tileAspectRatio: 1.0,
-    this.padding: EdgeInsets.zero
+    this.padding: EdgeInsets.zero,
+    List<Widget> children: _emptyWidgetList
   }) : super(key: key, children: children) {
-    assert(maxTileWidth != null);
+    assert(maxTileWidth != null && maxTileWidth >= 0.0);
+    assert(tileAspectRatio != null && tileAspectRatio > 0.0);
   }
 
   /// The maximum width of a tile in the grid.
@@ -1758,10 +1874,30 @@ class MaxTileWidthGrid extends GridRenderObjectWidgetBase {
   }
 }
 
-/// Supplies per-child data to the grid's [GridDelegate].
-class GridPlacementData<DataType, WidgetType extends RenderObjectWidget> extends ParentDataWidget<WidgetType> {
-  GridPlacementData({ Key key, this.placementData, Widget child })
-    : super(key: key, child: child);
+/// A widget that controls the placement of a child in a grid.
+///
+/// The [placementData] this widget associates with the child is interpreted by
+/// the grid's [GridDelegate] in its [GridDelegate.getChildPlacement] function.
+/// During layout, the grid calls the delegate's
+/// [GridDelegate.getChildPlacement] function for each child, passing the
+/// [placementData] associated with that child as context. The return value of
+/// [GridDelegate.getChildPlacement] is then used to determine the size and
+/// position of that child within the grid.
+///
+/// A [GridPlacementData] widget must be a descendant of a
+/// [GridRenderObjectWidget], and the path from the [GridPlacementData] widget
+/// to its enclosing [GridRenderObjectWidget] must contain only
+/// [StatelessWidget]s or [StatefulWidget]s (not other kinds of widgets, like
+/// [RenderObjectWidget]s).
+class GridPlacementData<DataType> extends ParentDataWidget<GridRenderObjectWidget> {
+  /// Creates a widget that controls placement of a child in a grid.
+  ///
+  /// The [placementData] and [child] arguments are required.
+  GridPlacementData({
+    Key key,
+    @required this.placementData,
+    @required Widget child
+  }) : super(key: key, child: child);
 
   /// Opaque data passed to the getChildPlacement method of the grid's [GridDelegate].
   final DataType placementData;
@@ -1785,22 +1921,28 @@ class GridPlacementData<DataType, WidgetType extends RenderObjectWidget> extends
   }
 }
 
-/// Uses the flex layout algorithm for its children.
+/// A widget that uses the flex layout algorithm for its children.
 ///
 /// For details about the flex layout algorithm, see [RenderFlex]. To control
 /// the flex of child widgets, see the [Flexible] widget.
 class Flex extends MultiChildRenderObjectWidget {
+  /// Creates a flex layout.
+  ///
+  /// The [direction], [mainAxisAlignment], and [crossAxisAlignment] arguments
+  /// must not be null. If [crossAxisAlignment] is
+  /// [CrossAxisAlignment.baseline], then [textBaseline] must not be null.
   Flex({
     Key key,
-    List<Widget> children: _emptyWidgetList,
     this.direction: FlexDirection.horizontal,
     this.mainAxisAlignment: MainAxisAlignment.start,
     this.crossAxisAlignment: CrossAxisAlignment.center,
-    this.textBaseline
+    this.textBaseline,
+    List<Widget> children: _emptyWidgetList
   }) : super(key: key, children: children) {
     assert(direction != null);
     assert(mainAxisAlignment != null);
     assert(crossAxisAlignment != null);
+    assert(crossAxisAlignment != CrossAxisAlignment.baseline || textBaseline != null);
   }
 
   /// The direction to use as the main axis.
@@ -1828,17 +1970,22 @@ class Flex extends MultiChildRenderObjectWidget {
   }
 }
 
-/// Lays out child elements in a row.
+/// A widget that lays out its children in a horizontal array.
 ///
 /// For details about the flex layout algorithm, see [RenderFlex]. To control
 /// the flex of child widgets, see the [Flexible] widget.
 class Row extends Flex {
+  /// Creates a horizontal array of children.
+  ///
+  /// The [direction], [mainAxisAlignment], and [crossAxisAlignment] arguments
+  /// must not be null. If [crossAxisAlignment] is
+  /// [CrossAxisAlignment.baseline], then [textBaseline] must not be null.
   Row({
     Key key,
-    List<Widget> children: _emptyWidgetList,
     MainAxisAlignment mainAxisAlignment: MainAxisAlignment.start,
     CrossAxisAlignment crossAxisAlignment: CrossAxisAlignment.center,
-    TextBaseline textBaseline
+    TextBaseline textBaseline,
+    List<Widget> children: _emptyWidgetList
   }) : super(
     children: children,
     key: key,
@@ -1849,17 +1996,22 @@ class Row extends Flex {
   );
 }
 
-/// Lays out child elements in a column.
+/// A widget that lays out its children in a vertical array.
 ///
 /// For details about the flex layout algorithm, see [RenderFlex]. To control
 /// the flex of child widgets, see the [Flexible] widget.
 class Column extends Flex {
+  /// Creates a vertical array of children.
+  ///
+  /// The [direction], [mainAxisAlignment], and [crossAxisAlignment] arguments
+  /// must not be null. If [crossAxisAlignment] is
+  /// [CrossAxisAlignment.baseline], then [textBaseline] must not be null.
   Column({
     Key key,
-    List<Widget> children: _emptyWidgetList,
     MainAxisAlignment mainAxisAlignment: MainAxisAlignment.start,
     CrossAxisAlignment crossAxisAlignment: CrossAxisAlignment.center,
-    TextBaseline textBaseline
+    TextBaseline textBaseline,
+    List<Widget> children: _emptyWidgetList
   }) : super(
     children: children,
     key: key,
@@ -1870,15 +2022,19 @@ class Column extends Flex {
   );
 }
 
-/// Controls how a child of a [Flex], [Row], or [Column] flexes.
+/// A widget that controls how a child of a [Flex], [Row], or [Column] flexes.
 ///
-/// This widget must be a descendant of a [Flex], [Row], or [Column], and the
-/// path from this widget to its enclosing [Flex], [Row], or [Column] must
-/// contain only [StatelessWidget]s or [StatefulWidget]s (not other kinds of
-/// widgets, like [RenderObjectWidget]s).
+/// A [Flexible] widget must be a descendant of a [Flex], [Row], or [Column],
+/// and the path from the [Flexible] widget to its enclosing [Flex], [Row], or
+/// [Column] must contain only [StatelessWidget]s or [StatefulWidget]s (not
+/// other kinds of widgets, like [RenderObjectWidget]s).
 class Flexible extends ParentDataWidget<Flex> {
-  Flexible({ Key key, this.flex: 1, Widget child })
-    : super(key: key, child: child);
+  /// Creates a widget that controls how a child of a [Flex], [Row], or [Column] flexes.
+  Flexible({
+    Key key,
+    this.flex: 1,
+    @required Widget child
+  }) : super(key: key, child: child);
 
   /// The flex factor to use for this child
   ///
@@ -1907,7 +2063,7 @@ class Flexible extends ParentDataWidget<Flex> {
   }
 }
 
-/// Implements the flow layout algorithm.
+/// A widget that implements the flow layout algorithm.
 ///
 /// Flow layouts are optimized for repositioning children using transformation
 /// matrices.
@@ -1938,10 +2094,12 @@ class Flow extends MultiChildRenderObjectWidget {
   ///
   /// Wraps each of the given children in a [RepaintBoundary] to avoid
   /// repainting the children when the flow repaints.
+  ///
+  /// The [delegate] argument must not be null.
   Flow({
     Key key,
-    List<Widget> children: _emptyWidgetList,
-    this.delegate
+    @required this.delegate,
+    List<Widget> children: _emptyWidgetList
   }) : super(key: key, children: RepaintBoundary.wrapAll(children)) {
     assert(delegate != null);
   }
@@ -1951,10 +2109,12 @@ class Flow extends MultiChildRenderObjectWidget {
   /// Does not wrap the given children in repaint boundaries, unlike the default
   /// constructor. Useful when the child is trivial to paint or already contains
   /// a repaint boundary.
+  ///
+  /// The [delegate] argument must not be null.
   Flow.unwrapped({
     Key key,
-    List<Widget> children: _emptyWidgetList,
-    this.delegate
+    this.delegate,
+    List<Widget> children: _emptyWidgetList
   }) : super(key: key, children: children) {
     assert(delegate != null);
   }
@@ -1996,10 +2156,10 @@ class Flow extends MultiChildRenderObjectWidget {
 class RichText extends LeafRenderObjectWidget {
   /// Creates a paragraph of rich text.
   ///
-  /// The [text] argument is required to be non-null.
+  /// The [text], [softWrap], and [overflow] arguments must not be null.
   RichText({
     Key key,
-    this.text,
+    @required this.text,
     this.textAlign,
     this.softWrap: true,
     this.overflow: TextOverflow.clip
@@ -2050,7 +2210,7 @@ class DefaultTextStyle extends InheritedWidget {
   /// from a the current default text style for a given [BuildContext].
   DefaultTextStyle({
     Key key,
-    this.style,
+    @required this.style,
     this.textAlign,
     this.softWrap: true,
     this.overflow: TextOverflow.clip,
@@ -2079,7 +2239,7 @@ class DefaultTextStyle extends InheritedWidget {
   /// [BuildContext].
   factory DefaultTextStyle.inherit({
     Key key,
-    BuildContext context,
+    @required BuildContext context,
     TextStyle style,
     TextAlign textAlign,
     bool softWrap,
@@ -2213,7 +2373,7 @@ class Text extends StatelessWidget {
   }
 }
 
-/// Displays a raw image.
+/// A widget that displays a [ui.Image] directly.
 ///
 /// This widget is rarely used directly. Instead, consider using [AssetImage] or
 /// [NetworkImage], depending on whather you wish to display an image from the
@@ -2224,6 +2384,9 @@ class Text extends StatelessWidget {
 ///  * [AssetImage]
 ///  * [NetworkImage]
 class RawImage extends LeafRenderObjectWidget {
+  /// Creates a widget that displays an image.
+  ///
+  /// The [scale] and [repeat] arguments must not be null.
   RawImage({
     Key key,
     this.image,
@@ -2235,7 +2398,10 @@ class RawImage extends LeafRenderObjectWidget {
     this.alignment,
     this.repeat: ImageRepeat.noRepeat,
     this.centerSlice
-  }) : super(key: key);
+  }) : super(key: key) {
+    assert(scale != null);
+    assert(repeat != null);
+  }
 
   /// The image to display.
   final ui.Image image;
@@ -2332,7 +2498,7 @@ class RawImage extends LeafRenderObjectWidget {
   }
 }
 
-/// Displays an [ImageResource].
+/// A widget that displays an [ImageResource].
 ///
 /// An image resource differs from an image in that it might yet let be loaded
 /// from the underlying storage (e.g., the asset bundle or the network) and it
@@ -2342,9 +2508,12 @@ class RawImage extends LeafRenderObjectWidget {
 /// [NetworkImage], depending on whather you wish to display an image from the
 /// assert bundle or from the network.
 class RawImageResource extends StatefulWidget {
+  /// Creates a widget that displays an [ImageResource].
+  ///
+  /// The [image] and [repeat] arguments must not be null.
   RawImageResource({
     Key key,
-    this.image,
+    @required this.image,
     this.width,
     this.height,
     this.color,
@@ -2465,20 +2634,27 @@ class _RawImageResourceState extends State<RawImageResource> {
   }
 }
 
-/// Displays an image loaded from the network.
+/// A widget that displays an image loaded from the network.
 class NetworkImage extends StatelessWidget {
+  /// Creates a widget that displays an image loaded from the network.
+  ///
+  /// The [src], [scale], and [repeat] arguments must not be null.
   NetworkImage({
     Key key,
-    this.src,
+    @required this.src,
     this.width,
     this.height,
-    this.scale : 1.0,
+    this.scale: 1.0,
     this.color,
     this.fit,
     this.alignment,
     this.repeat: ImageRepeat.noRepeat,
     this.centerSlice
-  }) : super(key: key);
+  }) : super(key: key) {
+    assert(src != null);
+    assert(scale != null);
+    assert(repeat != null);
+  }
 
   /// The URL from which to load the image.
   final String src;
@@ -2564,15 +2740,18 @@ class NetworkImage extends StatelessWidget {
   }
 }
 
-/// Sets a default asset bundle for its descendants.
+/// A widget that determines the default asset bundle for its descendants.
 ///
 /// For example, used by [AssetImage] to determine which bundle to use if no
 /// bundle is specified explicitly.
 class DefaultAssetBundle extends InheritedWidget {
+  /// Creates a widget that determines the default asset bundle for its descendants.
+  ///
+  /// The [bundle] and [child] arguments must not be null.
   DefaultAssetBundle({
     Key key,
-    this.bundle,
-    Widget child
+    @required this.bundle,
+    @required Widget child
   }) : super(key: key, child: child) {
     assert(bundle != null);
     assert(child != null);
@@ -2600,15 +2779,18 @@ class DefaultAssetBundle extends InheritedWidget {
   bool updateShouldNotify(DefaultAssetBundle old) => bundle != old.bundle;
 }
 
-/// Displays an image provided by an [ImageProvider].
+/// A widget that displays an image provided by an [ImageProvider].
 ///
 /// This widget lets you customize how images are loaded by supplying your own
 /// image provider. Internally, [NetworkImage] uses an [ImageProvider] that
 /// loads the image from the network.
 class AsyncImage extends StatelessWidget {
+  /// Creates a widget that displays an image provided by an [ImageProvider].
+  ///
+  /// The [provider] and [repeat] arguments must not be null.
   AsyncImage({
     Key key,
-    this.provider,
+    @required this.provider,
     this.width,
     this.height,
     this.color,
@@ -2616,7 +2798,10 @@ class AsyncImage extends StatelessWidget {
     this.alignment,
     this.repeat: ImageRepeat.noRepeat,
     this.centerSlice
-  }) : super(key: key);
+  }) : super(key: key) {
+    assert(provider != null);
+    assert(repeat != null);
+  }
 
   /// The object that will provide the image.
   final ImageProvider provider;
@@ -2695,7 +2880,7 @@ class AsyncImage extends StatelessWidget {
   }
 }
 
-/// Displays an image from an [AssetBundle].
+/// A widget that displays an image from an [AssetBundle].
 ///
 /// By default, asset image will load the image from the closest enclosing
 /// [DefaultAssetBundle].
@@ -2814,8 +2999,13 @@ class AssetImage extends StatelessWidget {
 /// widget enforces that restriction by keying itself using a [GlobalObjectKey]
 /// for the given render object.
 class WidgetToRenderBoxAdapter extends LeafRenderObjectWidget {
-  WidgetToRenderBoxAdapter({ RenderBox renderBox, this.onBuild })
-    : renderBox = renderBox,
+  /// Creates an adapter for placing a specific [RenderBox] in the widget tree.
+  ///
+  /// The [renderBox] argument must not be null.
+  WidgetToRenderBoxAdapter({
+    @required RenderBox renderBox,
+    this.onBuild
+  }) : renderBox = renderBox,
        // WidgetToRenderBoxAdapter objects are keyed to their render box. This
        // prevents the widget being used in the widget hierarchy in two different
        // places, which would cause the RenderBox to get inserted in multiple
@@ -2846,7 +3036,7 @@ class WidgetToRenderBoxAdapter extends LeafRenderObjectWidget {
 
 // EVENT HANDLING
 
-/// Calls callbacks in response to pointer events.
+/// A widget that calls callbacks in response to pointer events.
 ///
 /// Rather than listening for raw pointer events, consider listening for
 /// higher-level gestures using [GestureDetector].
@@ -2856,12 +3046,12 @@ class Listener extends SingleChildRenderObjectWidget {
   /// The [behavior] argument defaults to [HitTestBehavior.deferToChild].
   Listener({
     Key key,
-    Widget child,
     this.onPointerDown,
     this.onPointerMove,
     this.onPointerUp,
     this.onPointerCancel,
-    this.behavior: HitTestBehavior.deferToChild
+    this.behavior: HitTestBehavior.deferToChild,
+    Widget child
   }) : super(key: key, child: child) {
     assert(behavior != null);
   }
@@ -2929,7 +3119,7 @@ class Listener extends SingleChildRenderObjectWidget {
   }
 }
 
-/// Creates a separate display list for its child.
+/// A widget that creates a separate display list for its child.
 ///
 /// This widget creates a separate display list for its child, which
 /// can improve performance if the subtree repaints at different times than
@@ -2939,13 +3129,23 @@ class Listener extends SingleChildRenderObjectWidget {
 /// not, we can re-record its display list without re-recording the display list
 /// for the surround tree.
 class RepaintBoundary extends SingleChildRenderObjectWidget {
+  /// Creates a widget that isolates repaints.
   RepaintBoundary({ Key key, Widget child }) : super(key: key, child: child);
 
+  /// Wraps the given child in a [RepaintBoundary].
+  ///
+  /// The key for the [RepaintBoundary] is derived either from the child's key
+  /// (if the child has a non-null key) or from the given `childIndex`.
   factory RepaintBoundary.wrap(Widget child, int childIndex) {
     Key key = child.key != null ? new ValueKey<Key>(child.key) : new ValueKey<int>(childIndex);
     return new RepaintBoundary(key: key, child: child);
   }
 
+  /// Wraps each of the given children in [RepaintBoundary]s.
+  ///
+  /// The key for each [RepaintBoundary] is derived either from the wrapped
+  /// child's key (if the wrapped child has a non-null key) or from the wrapped
+  /// child's index in the list.
   static List<RepaintBoundary> wrapAll(List<Widget> widgets) {
     List<RepaintBoundary> result = new List<RepaintBoundary>(widgets.length);
     for (int i = 0; i < result.length; ++i)
@@ -2957,7 +3157,7 @@ class RepaintBoundary extends SingleChildRenderObjectWidget {
   RenderRepaintBoundary createRenderObject(BuildContext context) => new RenderRepaintBoundary();
 }
 
-/// A widget that os invisible during hit testing.
+/// A widget that is invisible during hit testing.
 ///
 /// When [ignoring] is `true`, this widget (and its subtree) is invisible
 /// to hit testing. It still consumes space during layout and paints its child
@@ -2974,9 +3174,9 @@ class IgnorePointer extends SingleChildRenderObjectWidget {
   /// render object will be ignored for semantics if [ignoring] is true.
   IgnorePointer({
     Key key,
-    Widget child,
     this.ignoring: true,
-    this.ignoringSemantics
+    this.ignoringSemantics,
+    Widget child
   }) : super(key: key, child: child) {
     assert(ignoring != null);
   }
@@ -3020,9 +3220,9 @@ class MetaData extends SingleChildRenderObjectWidget {
   /// The [behavior] argument defaults to [HitTestBehavior.deferToChild].
   MetaData({
     Key key,
-    Widget child,
     this.metaData,
-    this.behavior: HitTestBehavior.deferToChild
+    this.behavior: HitTestBehavior.deferToChild,
+    Widget child
   }) : super(key: key, child: child);
 
   /// Opaque meta data ignored by the render tree
@@ -3055,11 +3255,14 @@ class MetaData extends SingleChildRenderObjectWidget {
 
 // UTILITY NODES
 
-/// The Semantics widget annotates the widget tree with a description
-/// of the meaning of the widgets, so that accessibility tools, search
-/// engines, and other semantic analysis software can determine the
-/// meaning of the application.
+/// A widget that annotates the widget tree with a description of the meaning of the widgets.
+///
+/// Used by accessibility tools, search engines, and other semantic analysis
+/// software to determine the meaning of the application.
 class Semantics extends SingleChildRenderObjectWidget {
+  /// Creates a semantic annotation.
+  ///
+  /// The [container] argument must not be null.
   Semantics({
     Key key,
     Widget child,
@@ -3116,6 +3319,8 @@ class Semantics extends SingleChildRenderObjectWidget {
   }
 }
 
+/// A widget that merges the semantics of its descendants.
+///
 /// Causes all the semantics of the subtree rooted at this node to be
 /// merged into one node in the semantics tree. For example, if you
 /// have a widget with a Text node next to a checkbox widget, this
@@ -3134,32 +3339,38 @@ class Semantics extends SingleChildRenderObjectWidget {
 /// the first one in tree order will be the one to receive the
 /// callbacks.
 class MergeSemantics extends SingleChildRenderObjectWidget {
+  /// Creates a widget that merges the semantics of its descendants.
   MergeSemantics({ Key key, Widget child }) : super(key: key, child: child);
 
   @override
   RenderMergeSemantics createRenderObject(BuildContext context) => new RenderMergeSemantics();
 }
 
-/// Drops all semantics in this subtree.
+/// A widget that drops all the semantics of its descendants.
 ///
 /// This can be used to hide subwidgets that would otherwise be
 /// reported but that would only be confusing. For example, the
 /// material library's [Chip] widget hides the avatar since it is
 /// redundant with the chip label.
 class ExcludeSemantics extends SingleChildRenderObjectWidget {
+  /// Creates a widget that drops all the semantics of its descendants.
   ExcludeSemantics({ Key key, Widget child }) : super(key: key, child: child);
 
   @override
   RenderExcludeSemantics createRenderObject(BuildContext context) => new RenderExcludeSemantics();
 }
 
-/// Always builds the given child.
+/// A widget that builds its child.
 ///
 /// Useful for attaching a key to an existing widget.
 class KeyedSubtree extends StatelessWidget {
-  /// Creates a widget that always builds the given child.
-  KeyedSubtree({ Key key, this.child })
-    : super(key: key);
+  /// Creates a widget that builds its child.
+  KeyedSubtree({
+    Key key,
+    @required this.child
+  }) : super(key: key) {
+    assert(child != null);
+  }
 
   /// The widget below this widget in the tree.
   final Widget child;
@@ -3192,8 +3403,18 @@ class KeyedSubtree extends StatelessWidget {
 }
 
 /// A platonic widget that calls a closure to obtain its child widget.
+///
+/// See also:
+///
+///  * [StatefulBuilder] (which also has state)
 class Builder extends StatelessWidget {
-  Builder({ Key key, this.builder }) : super(key: key) {
+  /// Creates a widget that delegates its build to a callback.
+  ///
+  /// The [builder] argument must not be null.
+  Builder({
+    Key key,
+    @required this.builder
+  }) : super(key: key) {
     assert(builder != null);
   }
 
@@ -3210,17 +3431,40 @@ class Builder extends StatelessWidget {
   Widget build(BuildContext context) => builder(context);
 }
 
+/// Signature for the builder callback used by [StatefulBuilder].
+///
+/// Call [setState] to schedule the [StatefulBuilder] to rebuild.
 typedef Widget StatefulWidgetBuilder(BuildContext context, StateSetter setState);
+
+/// A platonic widget that both has state and calls a closure to obtain its child widget.
+///
+/// See also:
+///
+///  * [Builder] (which lacks state)
 class StatefulBuilder extends StatefulWidget {
-  StatefulBuilder({ Key key, this.builder }) : super(key: key) {
+  /// Creates a widget that both has state and delegates its build to a callback.
+  ///
+  /// The [builder] argument must not be null.
+  StatefulBuilder({
+    Key key,
+    @required this.builder
+  }) : super(key: key) {
     assert(builder != null);
   }
 
+  /// Called to obtain the child widget.
+  ///
+  /// This function is called whenever this widget is included in its parent's
+  /// build and the old widget (if any) that it synchronizes with has a distinct
+  /// object identity. Typically the parent's build method will construct
+  /// a new tree of widgets and so a new Builder child will not be [identical]
+  /// to the corresponding old one.
   final StatefulWidgetBuilder builder;
 
   @override
   _StatefulBuilderState createState() => new _StatefulBuilderState();
 }
+
 class _StatefulBuilderState extends State<StatefulBuilder> {
   @override
   Widget build(BuildContext context) => config.builder(context, setState);

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

@@ -5,6 +5,7 @@
 import 'dart:collection';
 
 import 'package:flutter/rendering.dart';
+import 'package:meta/meta.dart';
 
 import 'debug.dart';
 import 'framework.dart';
@@ -239,8 +240,11 @@ class _TableElement extends RenderObjectElement {
 }
 
 class TableCell extends ParentDataWidget<Table> {
-  TableCell({ Key key, this.verticalAlignment, Widget child })
-    : super(key: key, child: child);
+  TableCell({
+    Key key,
+    this.verticalAlignment,
+    @required Widget child
+  }) : super(key: key, child: child);
 
   final TableCellVerticalAlignment verticalAlignment;