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/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;