More documentation. (#10953)

Applies comments I missed from https://github.com/flutter/flutter/pull/10904.

dev/bots/analyze-sample-code.dart

@@ -120,7 +120,7 @@ Future<Null> main() async {
             assert(block.isEmpty);
             startLine = new Line(file.path, lineNumber + 1, 3);
             inPreamble = true;
-          } else if (trimmedLine == '/// ## Sample code') {
+          } else if (trimmedLine == '/// ## Sample code' || trimmedLine == '/// ### Sample code') {
             inSampleSection = true;
             foundDart = false;
             sampleCodeSections += 1;

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

@@ -325,7 +325,7 @@ class SliverGridDelegateWithFixedCrossAxisCount extends SliverGridDelegate {
   }
 }
 
-/// Creates grid layouts with tiles that have a maximum cross-axis extent.
+/// Creates grid layouts with tiles that each have a maximum cross-axis extent.
 ///
 /// This delegate will select a cross-axis extent for the tiles that is as
 /// large as possible subject to the following conditions:

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

@@ -172,12 +172,22 @@ class Image extends StatefulWidget {
   /// directory with the name `cat.png` (the paths are relative to the
   /// `pubspec.yaml` file).
   ///
+  /// On a device with a 4.0 device pixel ratio, the `images/3.5x/cat.png` asset
+  /// would be used. On a device with a 1.0 device pixel ratio, the
+  /// `images/cat.png` resource would be used.
+  ///
+  /// The `images/cat.png` image can be omitted from disk (though it must still
+  /// be present in the manifest). If it is omitted, then on a device with a 1.0
+  /// device pixel ratio, the `images/2x/cat.png` image would be used instead.
+  ///
   /// 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.
+  ///  * <https://flutter.io/assets-and-images/>, an introduction to assets in
+  ///    Flutter.
   Image.asset(String name, {
     Key key,
     AssetBundle bundle,

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

@@ -454,6 +454,45 @@ abstract class BoxScrollView extends ScrollView {
 /// [SliverGrid] or [SliverAppBar], can be put in the [CustomScrollView.slivers]
 /// list.
 ///
+/// ### Sample code
+///
+/// Here are two brief snippets showing a [ListView] and its equivalent using
+/// [CustomScrollView]:
+///
+/// ```dart
+/// new ListView(
+///   shrinkWrap: true,
+///   padding: const EdgeInsets.all(20.0),
+///   children: <Widget>[
+///     const Text('I\'m dedicating every day to you'),
+///     const Text('Domestic life was never quite my style'),
+///     const Text('When you smile, you knock me out, I fall apart'),
+///     const Text('And I thought I was so smart'),
+///   ],
+/// )
+/// ```
+///
+/// ```dart
+/// new CustomScrollView(
+///   shrinkWrap: true,
+///   slivers: <Widget>[
+///     new SliverPadding(
+///       padding: const EdgeInsets.all(20.0),
+///       sliver: new SliverList(
+///         delegate: new SliverChildListDelegate(
+///           <Widget>[
+///             const Text('I\'m dedicating every day to you'),
+///             const Text('Domestic life was never quite my style'),
+///             const Text('When you smile, you knock me out, I fall apart'),
+///             const Text('And I thought I was so smart'),
+///           ],
+///         ),
+///       ),
+///     ),
+///   ],
+/// )
+/// ```
+///
 /// See also:
 ///
 ///  * [SingleChildScrollView], which is a scrollable widget that has a single
@@ -603,10 +642,13 @@ class ListView extends BoxScrollView {
 
 /// A scrollable, 2D array of widgets.
 ///
+/// The main axis direction of a grid is the direction in which it scrolls (the
+/// [scrollDirection]).
+///
 /// The most commonly used grid layouts are [GridView.count], which creates a
 /// layout with a fixed number of tiles in the cross axis, and
 /// [GridView.extent], which creates a layout with tiles that have a maximum
-/// cross-axis extent. A custom [SliverGridDelegate] can produce an aribtrary 2D
+/// cross-axis extent. A custom [SliverGridDelegate] can produce an arbitrary 2D
 /// arrangement of children, including arrangements that are unaligned or
 /// overlapping.
 ///
@@ -657,9 +699,54 @@ class ListView extends BoxScrollView {
 /// 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]
+/// [SliverList] or [SliverAppBar], can be put in the [CustomScrollView.slivers]
 /// list.
 ///
+/// ### Sample code
+///
+/// Here are two brief snippets showing a [GridView] and its equivalent using
+/// [CustomScrollView]:
+///
+/// ```dart
+/// new GridView.count(
+///   primary: false,
+///   padding: const EdgeInsets.all(20.0),
+///   crossAxisSpacing: 10.0,
+///   crossAxisCount: 2,
+///   children: <Widget>[
+///     const Text('He\'d have you all unravel at the'),
+///     const Text('Heed not the rabble'),
+///     const Text('Sound of screams but the'),
+///     const Text('Who scream'),
+///     const Text('Revolution is coming...'),
+///     const Text('Revolution, they...'),
+///   ],
+/// )
+/// ```
+///
+/// ```dart
+/// new CustomScrollView(
+///   primary: false,
+///   slivers: <Widget>[
+///     new SliverPadding(
+///       padding: const EdgeInsets.all(20.0),
+///       sliver: new SliverGrid.count(
+///         crossAxisSpacing: 10.0,
+///         crossAxisCount: 2,
+///         children: <Widget>[
+///           const Text('He\'d have you all unravel at the'),
+///           const Text('Heed not the rabble'),
+///           const Text('Sound of screams but the'),
+///           const Text('Who scream'),
+///           const Text('Revolution is coming...'),
+///           const Text('Revolution, they...'),
+///         ],
+///       ),
+///     ),
+///   ],
+/// )
+/// ```
+///
 /// See also:
 ///
 ///  * [SingleChildScrollView], which is a scrollable widget that has a single
@@ -810,8 +897,8 @@ class GridView extends BoxScrollView {
     padding: padding,
   );
 
-  /// Creates a scrollable, 2D array of widgets with tiles that have a maximum
-  /// cross-axis extent.
+  /// Creates a scrollable, 2D array of widgets with tiles that each have a
+  /// maximum cross-axis extent.
   ///
   /// Uses a [SliverGridDelegateWithMaxCrossAxisExtent] as the [gridDelegate].
   ///

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

@@ -393,6 +393,9 @@ class SliverFixedExtentList extends SliverMultiBoxAdaptorWidget {
 /// [gridDelegate]. Each child is forced to have the size specified by the
 /// [gridDelegate].
 ///
+/// The main axis direction of a grid is the direction in which it scrolls; the
+/// cross axis direction is the orthogonal direction.
+///
 /// ## Sample code
 ///
 /// This example, which would be inserted into a [CustomScrollView.slivers]
@@ -441,6 +444,10 @@ class SliverGrid extends SliverMultiBoxAdaptorWidget {
   ///
   /// Uses a [SliverGridDelegateWithFixedCrossAxisCount] as the [gridDelegate],
   /// and a [SliverChildListDelegate] as the [delegate].
+  ///
+  /// See also:
+  ///
+  ///  * [new GridView.count], the equivalent constructor for [GridView] widgets.
   SliverGrid.count({
     Key key,
     @required int crossAxisCount,
@@ -457,10 +464,14 @@ class SliverGrid extends SliverMultiBoxAdaptorWidget {
        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.
+  /// arrangement with tiles that each have a maximum cross-axis extent.
   ///
   /// Uses a [SliverGridDelegateWithMaxCrossAxisExtent] as the [gridDelegate],
   /// and a [SliverChildListDelegate] as the [delegate].
+  ///
+  /// See also:
+  ///
+  ///  * [new GridView.extent], the equivalent constructor for [GridView] widgets.
   SliverGrid.extent({
     Key key,
     @required double maxCrossAxisExtent,