Add documentation. Also, add constructors to SliverGrid. (#10904)

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

@@ -161,7 +161,7 @@ class ImageConfiguration {
 ///
 /// The following shows the code required to write a widget that fully conforms
 /// to the [ImageProvider] and [Widget] protocols. (It is essentially a
-/// bare-bones version of the [Image] widget.)
+/// bare-bones version of the [widgets.Image] widget.)
 ///
 /// ```dart
 /// class MyImage extends StatefulWidget {

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

@@ -152,6 +152,7 @@ class AssetImage extends AssetBundleImageProvider {
       mapping[_parseScale(candidate)] = candidate;
     mapping[_naturalResolution] = main;
     // TODO(ianh): implement support for config.locale, config.size, config.platform
+    // (then document this over in the Image.asset docs)
     return _findNearest(mapping, config.devicePixelRatio);
   }
 
@@ -177,7 +178,7 @@ class AssetImage extends AssetBundleImageProvider {
     final Match match = _extractRatioRegExp.firstMatch(key);
     if (match != null && match.groupCount > 0)
       return double.parse(match.group(1));
-    return _naturalResolution;
+    return _naturalResolution; // i.e. default to 1.0x
   }
 
   @override

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

@@ -23,6 +23,16 @@ import 'package:flutter/foundation.dart';
 /// method to reparent your [FocusNode] if your widget moves from one
 /// location in the tree to another.
 ///
+/// ## Lifetime
+///
+/// Focus nodes are long-lived objects. For example, if a stateful widget has a
+/// focusable child widget, it should create a [FocusNode] in the
+/// [State.initState] method, and [dispose] it in the [State.dispose] method,
+/// providing the same [FocusNode] to the focusable child each time the
+/// [State.build] method is run. In particular, creating a [FocusNode] each time
+/// [State.build] is invoked will cause the focus to be lost each time the
+/// widget is built.
+///
 /// See also:
 ///
 ///  * [FocusScopeNode], which is an interior node in the focus tree.

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

@@ -133,13 +133,51 @@ class Image extends StatefulWidget {
   /// If the `bundle` argument is omitted or null, then the
   /// [DefaultAssetBundle] will be used.
   ///
-  /// If the `scale` argument is omitted or null, then pixel-density-aware asset
-  /// resolution will be attempted.
+  /// By default, the exact asset specified will be used. In addition:
   ///
-  /// If [width] and [height] are both specified, and [scale] is not, then
-  /// size-aware asset resolution will be attempted also.
+  /// * If the `scale` argument is omitted or null, then pixel-density-aware
+  ///   asset resolution will be attempted.
+  //
+  // TODO(ianh): Implement the following (see ../services/image_resolution.dart):
+  // ///
+  // /// * If [width] and [height] are both specified, and [scale] is not, then
+  // ///   size-aware asset resolution will be attempted also, with the given
+  // ///   dimensions interpreted as logical pixels.
+  // ///
+  // /// * If the images have platform or locale variants, the current platform
+  // ///   and locale is taken into account during asset resolution as well.
   ///
   /// The [name] and [repeat] arguments must not be null.
+  ///
+  /// ## Sample code
+  ///
+  /// Suppose that the project's `pubspec.yaml` file contains the following:
+  ///
+  /// ```yaml
+  /// flutter:
+  ///   assets:
+  ///     - images/cat.png
+  ///     - images/2x/cat.png
+  ///     - images/3.5x/cat.png
+  /// ```
+  ///
+  /// On a screen with a device pixel ratio of 2.0, the following widget would
+  /// render the `images/2x/cat.png` file:
+  ///
+  /// ```dart
+  /// new Image.asset('images/cat.png')
+  /// ```
+  ///
+  /// This corresponds to the file that is in the project's `images/2x/`
+  /// directory with the name `cat.png` (the paths are relative to the
+  /// `pubspec.yaml` file).
+  ///
+  /// See also:
+  ///
+  ///  * [AssetImage], which is used to implement the behavior when the scale is
+  ///    omitted.
+  ///  * [ExactAssetImage], which is used to implement the behavior when the
+  ///    scale is present.
   Image.asset(String name, {
     Key key,
     AssetBundle bundle,

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

@@ -420,6 +420,40 @@ abstract class BoxScrollView extends ScrollView {
 /// )
 /// ```
 ///
+/// ## Transitioning to [CustomScrollView]
+///
+/// A [ListView] is basically a [CustomScrollView] with a single [SliverList] in
+/// its [slivers] property.
+///
+/// If [ListView] is no longer sufficient, for example because the scroll view
+/// is to have both a list and a grid, or because the list is to be combined
+/// with a [SliverAppBar], etc, it is straight-forward to port code from using
+/// [ListView] to using [CustomScrollView] directly.
+///
+/// The [key], [scrollDirection], [reverse], [controller], [primary], [physics],
+/// and [shrinkWrap] properties on [ListView] map directly to the identically
+/// named properties on [CustomScrollView].
+///
+/// The [CustomScrollView.slivers] property should be a list containing either a
+/// [SliverList] or a [SliverFixedExtentList]; the former if [itemExtent] on the
+/// [ListView] was null, and the latter if [itemExtent] was not null.
+///
+/// The [childrenDelegate] property on [ListView] corresponds to the
+/// [SliverList.delegate] (or [SliverFixedExtentList.delegate]) property. The
+/// [new ListView] constructor's `children` argument corresponds to the
+/// [childrenDelegate] being a [SliverChildListDelegate] with that same
+/// argument. The [new ListView.builder] constructor's `itemBuilder` and
+/// `childCount` arguments correspond to the [childrenDelegate] being a
+/// [SliverChildBuilderDelegate] with the matching arguments.
+///
+/// The [padding] property corresponds to having a [SliverPadding] in the
+/// [CustomScrollView.slivers] property instead of the list itself, and having
+/// the [SliverList] instead be a child of the [SliverPadding].
+///
+/// Once code has been ported to use [CustomScrollView], other slivers, such as
+/// [SliverGrid] or [SliverAppBar], can be put in the [CustomScrollView.slivers]
+/// list.
+///
 /// See also:
 ///
 ///  * [SingleChildScrollView], which is a scrollable widget that has a single
@@ -585,6 +619,47 @@ class ListView extends BoxScrollView {
 ///
 /// To create a linear array of children, use a [ListView].
 ///
+/// ## Transitioning to [CustomScrollView]
+///
+/// A [GridView] is basically a [CustomScrollView] with a single [SliverGrid] in
+/// its [slivers] property.
+///
+/// If [GridView] is no longer sufficient, for example because the scroll view
+/// is to have both a grid and a list, or because the grid is to be combined
+/// with a [SliverAppBar], etc, it is straight-forward to port code from using
+/// [GridView] to using [CustomScrollView] directly.
+///
+/// The [key], [scrollDirection], [reverse], [controller], [primary], [physics],
+/// and [shrinkWrap] properties on [GridView] map directly to the identically
+/// named properties on [CustomScrollView].
+///
+/// The [CustomScrollView.slivers] property should be a list containing just a
+/// [SliverGrid].
+///
+/// The [childrenDelegate] property on [GridView] corresponds to the
+/// [SliverGrid.delegate] property, and the [gridDelegate] property on the
+/// [GridView] corresponds to the [SliverGrid.gridDelegate] property.
+///
+/// The [new GridView], [new GridView.count], and [new GridView.extent]
+/// constructors' `children` arguments correspond to the [childrenDelegate]
+/// being a [SliverChildListDelegate] with that same argument. The [new
+/// GridView.builder] constructor's `itemBuilder` and `childCount` arguments
+/// correspond to the [childrenDelegate] being a [SliverChildBuilderDelegate]
+/// with the matching arguments.
+///
+/// The [new GridView.count] and [new GridView.extent] constructors create
+/// custom grid delegates, and have equivalently named constructors on
+/// [SliverGrid] to ease the transition: [new SliverGrid.count] and [new
+/// SliverGrid.extent] respectively.
+///
+/// The [padding] property corresponds to having a [SliverPadding] in the
+/// [CustomScrollView.slivers] property instead of the grid itself, and having
+/// the [SliverGrid] instead be a child of the [SliverPadding].
+///
+/// Once code has been ported to use [CustomScrollView], other slivers, such as
+/// [SliverGrid] or [SliverAppBar], can be put in the [CustomScrollView.slivers]
+/// list.
+///
 /// See also:
 ///
 ///  * [SingleChildScrollView], which is a scrollable widget that has a single
@@ -700,6 +775,10 @@ class GridView extends BoxScrollView {
   /// the cross axis.
   ///
   /// Uses a [SliverGridDelegateWithFixedCrossAxisCount] as the [gridDelegate].
+  ///
+  /// See also:
+  ///
+  ///  * [new SliverGrid.count], the equivalent constructor for [SliverGrid].
   GridView.count({
     Key key,
     Axis scrollDirection: Axis.vertical,
@@ -735,6 +814,10 @@ class GridView extends BoxScrollView {
   /// cross-axis extent.
   ///
   /// Uses a [SliverGridDelegateWithMaxCrossAxisExtent] as the [gridDelegate].
+  ///
+  /// See also:
+  ///
+  ///  * [new SliverGrid.extent], the equivalent constructor for [SliverGrid].
   GridView.extent({
     Key key,
     Axis scrollDirection: Axis.vertical,

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

@@ -436,6 +436,46 @@ class SliverGrid extends SliverMultiBoxAdaptorWidget {
     @required this.gridDelegate,
   }) : super(key: key, delegate: delegate);
 
+  /// Creates a sliver that places multiple box children in a two dimensional
+  /// arrangement with a fixed number of tiles in the cross axis.
+  ///
+  /// Uses a [SliverGridDelegateWithFixedCrossAxisCount] as the [gridDelegate],
+  /// and a [SliverChildListDelegate] as the [delegate].
+  SliverGrid.count({
+    Key key,
+    @required int crossAxisCount,
+    double mainAxisSpacing: 0.0,
+    double crossAxisSpacing: 0.0,
+    double childAspectRatio: 1.0,
+    List<Widget> children: const <Widget>[],
+  }) : gridDelegate = new SliverGridDelegateWithFixedCrossAxisCount(
+         crossAxisCount: crossAxisCount,
+         mainAxisSpacing: mainAxisSpacing,
+         crossAxisSpacing: crossAxisSpacing,
+         childAspectRatio: childAspectRatio,
+       ),
+       super(key: key, delegate: new SliverChildListDelegate(children));
+
+  /// Creates a sliver that places multiple box children in a two dimensional
+  /// arrangement with tiles that have a maximum cross-axis extent.
+  ///
+  /// Uses a [SliverGridDelegateWithMaxCrossAxisExtent] as the [gridDelegate],
+  /// and a [SliverChildListDelegate] as the [delegate].
+  SliverGrid.extent({
+    Key key,
+    @required double maxCrossAxisExtent,
+    double mainAxisSpacing: 0.0,
+    double crossAxisSpacing: 0.0,
+    double childAspectRatio: 1.0,
+    List<Widget> children: const <Widget>[],
+  }) : gridDelegate = new SliverGridDelegateWithMaxCrossAxisExtent(
+         maxCrossAxisExtent: maxCrossAxisExtent,
+         mainAxisSpacing: mainAxisSpacing,
+         crossAxisSpacing: crossAxisSpacing,
+         childAspectRatio: childAspectRatio,
+       ),
+       super(key: key, delegate: new SliverChildListDelegate(children));
+
   /// The delegate that controls the size and position of the children.
   final SliverGridDelegate gridDelegate;