Much work on the documentation (#10331)

Minor fixes throughout, e.g. removing trailing commas from the end of sample code expressions, changing headings to "sample code" more consistently, removing stale todos, fix typos in a private method name, minor grammar fixes, added some clarifications to CircularProgressIndicator, LinearProgressIndicator, CrossAxisAlignment, added some cross-references to various members, made it slightly clearer that layout algorithms are implementation details.

Clarified "elevation" throughout.

Added docs to InkResponse and InkWell.

Added sample code for: SliverAppBar, Card, ListTile, EdgeInsets, Row, Column, CustomScrollView, ListView, SliverFixedExtentList, and SliverGrid.

Fixes #10317.
Fixes #10316.
Fixes #10267. (sort of, see comment therein)
Fixes #9331. (sort of, see comment therein)
Fixes #9407. (sort of, see comment therein)

examples/flutter_gallery/lib/demo/material/cards_demo.dart

@@ -110,7 +110,6 @@ class TravelDestinationItem extends StatelessWidget {
               ),
             ),
             // share, explore buttons
-            // TODO(abarth): The theme and the bar should be part of card.
             new ButtonTheme.bar(
               child: new ButtonBar(
                 alignment: MainAxisAlignment.start,

packages/flutter/lib/src/animation/tween.dart

@@ -90,7 +90,7 @@ class _ChainedEvaluation<T> extends Animatable<T> {
 /// which results in two [Animation] separate objects, each configured with a
 /// single [Tween].
 ///
-/// ## Sample usage
+/// ## Sample code
 ///
 /// Suppose `_controller` is an [AnimationController], and we want to create an
 /// [Animation<Offset>] that is controlled by that controller, and save it in

packages/flutter/lib/src/cupertino/slider.dart

@@ -85,7 +85,7 @@ class CupertinoSlider extends StatefulWidget {
   ///       _duelCommandment = newValue.round();
   ///     });
   ///   },
-  /// ),
+  /// )
   /// ```
   final ValueChanged<double> onChanged;
 

packages/flutter/lib/src/cupertino/switch.dart

@@ -57,7 +57,7 @@ class CupertinoSwitch extends StatefulWidget {
   ///       _giveVerse = newValue;
   ///     });
   ///   },
-  /// ),
+  /// )
   /// ```
   final ValueChanged<bool> onChanged;
 

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

@@ -269,7 +269,8 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget {
   ///  * [PreferredSize], which can be used to give an arbitrary widget a preferred size.
   final PreferredSizeWidget bottom;
 
-  /// The z-coordinate at which to place this app bar.
+  /// The z-coordinate at which to place this app bar. This controls the size of
+  /// the shadow below the app bar.
   ///
   /// Defaults to 4, the appropriate elevation for app bars.
   final double elevation;
@@ -694,6 +695,27 @@ class _SliverAppBarDelegate extends SliverPersistentHeaderDelegate {
 /// [actions], above the [bottom] (if any). If a [flexibleSpace] widget is
 /// specified then it is stacked behind the toolbar and the bottom widget.
 ///
+/// ## Sample code
+///
+/// This is an example that could be included in a [CustomScrollView]'s
+/// [CustomScrollView.slivers] list:
+///
+/// ```dart
+/// new SliverAppBar(
+///   expandedHeight: 150.0,
+///   flexibleSpace: const FlexibleSpaceBar(
+///     title: const Text('Available seats'),
+///   ),
+///   actions: <Widget>[
+///     new IconButton(
+///       icon: const Icon(Icons.add_circle),
+///       tooltip: 'Add new entry',
+///       onPressed: () { /* ... */ },
+///     ),
+///   ]
+/// )
+/// ```
+///
 /// See also:
 ///
 ///  * [CustomScrollView], which integrates the [SliverAppBar] into its
@@ -800,7 +822,7 @@ class SliverAppBar extends StatefulWidget {
   final PreferredSizeWidget bottom;
 
   /// The z-coordinate at which to place this app bar when it is above other
-  /// content.
+  /// content. This controls the size of the shadow below the app bar.
   ///
   /// Defaults to 4, the appropriate elevation for app bars.
   ///

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

@@ -195,14 +195,27 @@ class MaterialButton extends StatefulWidget {
   /// Defaults to the highlight color from the [Theme].
   final Color highlightColor;
 
-  /// The z-coordinate at which to place this button.
+  /// The z-coordinate at which to place this button. This controls the size of
+  /// the shadow below the button.
   ///
   /// Defaults to 0.
+  ///
+  /// See also:
+  ///
+  ///  * [FlatButton], a material button specialized for the case where the
+  ///    elevation is zero.
+  ///  * [RaisedButton], a material button specialized for the case where the
+  ///    elevation is non-zero.
   final double elevation;
 
-  /// The z-coordinate at which to place this button when highlighted.
+  /// The z-coordinate at which to place this button when highlighted. This
+  /// controls the size of the shadow below the button.
   ///
   /// Defaults to 0.
+  ///
+  /// See also:
+  ///
+  ///  * [elevation], the default elevation.
   final double highlightElevation;
 
   /// The smallest horizontal extent that the button will occupy.

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

@@ -11,11 +11,51 @@ import 'material.dart';
 /// A card is a sheet of [Material] used to represent some related information,
 /// for example an album, a geographical location, a meal, contact details, etc.
 ///
+/// ## Sample code
+///
+/// Here is an example of using a [Card] widget.
+///
+/// ```dart
+/// new Card(
+///   child: new Column(
+///     mainAxisSize: MainAxisSize.min,
+///     children: <Widget>[
+///       const ListTile(
+///         leading: const Icon(Icons.album),
+///         title: const Text('The Enchanted Nightingale'),
+///         subtitle: const Text('Music by Julie Gable. Lyrics by Sidney Stein.'),
+///       ),
+///       new ButtonTheme.bar( // make buttons use the appropriate styles for cards
+///         child: new ButtonBar(
+///           children: <Widget>[
+///             new FlatButton(
+///               child: const Text('BUY TICKETS'),
+///               onPressed: () { /* ... */ },
+///             ),
+///             new FlatButton(
+///               child: const Text('LISTEN'),
+///               onPressed: () { /* ... */ },
+///             ),
+///           ],
+///         ),
+///       ),
+///     ],
+///   ),
+/// )
+/// ```
+///
+/// This is what it would look like:
+///
+/// ![A card with a slight shadow, consisting of two rows, one with an icon and
+/// some text describing a musical, and the other with buttons for buying
+/// tickets or listening to the show.]
+/// (https://flutter.github.io/assets-for-api-docs/material/card.png)
+///
 /// See also:
 ///
 ///  * [ListTile], to display icons and text in a card.
 ///  * [ButtonBar], to display buttons at the bottom of a card. Typically these
-///    would be styled using a ButtonTheme created with [new ButtonTheme.bar].
+///    would be styled using a [ButtonTheme] created with [new ButtonTheme.bar].
 ///  * [showDialog], to display a modal card.
 ///  * <https://material.google.com/components/cards.html>
 class Card extends StatelessWidget {
@@ -24,7 +64,7 @@ class Card extends StatelessWidget {
     Key key,
     this.color,
     this.elevation: 2.0,
-    this.child
+    this.child,
   }) : super(key: key);
 
   /// The widget below this widget in the tree.
@@ -33,7 +73,8 @@ class Card extends StatelessWidget {
   /// The color of material used for this card.
   final Color color;
 
-  /// The z-coordinate at which to place this card.
+  /// The z-coordinate at which to place this card. This controls the size of
+  /// the shadow below the card.
   ///
   /// Defaults to 2, the appropriate elevation for cards.
   final double elevation;

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

@@ -80,7 +80,7 @@ class Checkbox extends StatefulWidget {
   ///       _throwShotAway = newValue;
   ///     });
   ///   },
-  /// ),
+  /// )
   /// ```
   final ValueChanged<bool> onChanged;
 

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

@@ -118,7 +118,7 @@ class CheckboxListTile extends StatelessWidget {
   ///     });
   ///   },
   ///   title: new Text('Throw away your shot'),
-  /// ),
+  /// )
   /// ```
   final ValueChanged<bool> onChanged;
 

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

@@ -72,7 +72,8 @@ class Drawer extends StatelessWidget {
     this.child
   }) : super(key: key);
 
-  /// The z-coordinate at which to place this drawer.
+  /// The z-coordinate at which to place this drawer. This controls the size of
+  /// the shadow below the drawer.
   ///
   /// Defaults to 16, the appropriate elevation for drawers.
   final double elevation;

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

@@ -76,15 +76,22 @@ class FloatingActionButton extends StatefulWidget {
   /// If this is set to null, the button will be disabled.
   final VoidCallback onPressed;
 
-  /// The z-coordinate at which to place this button.
+  /// The z-coordinate at which to place this button. This controls the size of
+  /// the shadow below the floating action button.
   ///
   /// Defaults to 6, the appropriate elevation for floating action buttons.
   final double elevation;
 
-  /// The z-coordinate at which to place this button when the user is touching the button.
+  /// The z-coordinate at which to place this button when the user is touching
+  /// the button. This controls the size of the shadow below the floating action
+  /// button.
   ///
   /// Defaults to 12, the appropriate elevation for floating action buttons
   /// while they are being touched.
+  ///
+  /// See also:
+  ///
+  ///  * [elevation], the default elevation.
   final double highlightElevation;
 
   /// Controls the size of this button.

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

@@ -29,12 +29,12 @@ RectCallback _getClipCallback(RenderBox referenceBox, bool containedInkWell, Rec
 double _getTargetRadius(RenderBox referenceBox, bool containedInkWell, RectCallback rectCallback, Offset position) {
   if (containedInkWell) {
     final Size size = rectCallback != null ? rectCallback().size : referenceBox.size;
-    return _getSplashRadiusForPoistionInSize(size, position);
+    return _getSplashRadiusForPositionInSize(size, position);
   }
   return Material.defaultSplashRadius;
 }
 
-double _getSplashRadiusForPoistionInSize(Size bounds, Offset position) {
+double _getSplashRadiusForPositionInSize(Size bounds, Offset position) {
   final double d1 = (position - bounds.topLeft(Offset.zero)).distance;
   final double d2 = (position - bounds.topRight(Offset.zero)).distance;
   final double d3 = (position - bounds.bottomLeft(Offset.zero)).distance;

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

@@ -21,6 +21,25 @@ import 'theme.dart';
 /// For a variant of this widget that is specialized for rectangular areas that
 /// always clip splashes, see [InkWell].
 ///
+/// The following two diagrams show how [InkResponse] looks when tapped if the
+/// [highlightShape] is [BoxShape.circle] (the default) and [containedInkWell]
+/// is false (also the default). The first diagram shows how it looks if the
+/// [InkResponse] is relatively large, the second shows how it looks if it is
+/// small. The main thing to notice is that the splashes happily exceed the
+/// bounds of the widget (because [containedInkWell] is false).
+///
+/// ![The highlight is a disc centered in the box, smaller than the child widget.]
+/// (https://flutter.github.io/assets-for-api-docs/material/ink_response_large.png)
+/// ![The highlight is a disc overflowing the box, centered on the child.]
+/// (https://flutter.github.io/assets-for-api-docs/material/ink_response_small.png)
+///
+/// The following diagram shows the effect when the [InkResponse] has a
+/// [highlightShape] of [BoxShape.rectangle] with [containedInkWell] set to
+/// true. These are the values used by [InkWell].
+///
+/// ![The highlight is a rectangle the size of the box.]
+/// (https://flutter.github.io/assets-for-api-docs/material/ink_well.png)
+///
 /// Must have an ancestor [Material] widget in which to cause ink reactions.
 ///
 /// If a Widget uses this class directly, it should include the following line
@@ -267,8 +286,16 @@ class _InkResponseState<T extends InkResponse> extends State<T> {
 
 /// A rectangular area of a [Material] that responds to touch.
 ///
+/// For a variant of this widget that does not clip splashes, see [InkResponse].
+///
 /// Must have an ancestor [Material] widget in which to cause ink reactions.
 ///
+/// The following diagram shows how an [InkWell] looks when tapped, when using
+/// default values.
+///
+/// ![The highlight is a rectangle the size of the box.]
+/// (https://flutter.github.io/assets-for-api-docs/material/ink_well.png)
+///
 /// If a Widget uses this class directly, it should include the following line
 /// at the top of its build function to call [debugCheckHasMaterial]:
 ///

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

@@ -151,10 +151,38 @@ enum ListTileControlAffinity {
 /// height based on their contents. If you are looking for a widget that allows
 /// for arbitrary layout in a row, consider [Row].
 ///
-/// List tiles are typically used in [ListView]s, [Drawer]s, and [Card]s.
+/// List tiles are typically used in [ListView]s, or arranged in [Column]s in
+/// [Drawer]s and [Card]s.
 ///
 /// Requires one of its ancestors to be a [Material] widget.
 ///
+/// ## Sample code
+///
+/// Here is a simple tile with an icon and some text.
+///
+/// ```dart
+/// new ListTile(
+///   leading: const Icon(Icons.event_seat),
+///   title: const Text('The seat for the narrator'),
+/// )
+/// ```
+///
+/// Tiles can be much more elaborate. Here is a tile which can be tapped, but
+/// which is disabled when the `_act` variable is not 2. When the tile is
+/// tapped, the whole row has an ink splash effect (see [InkWell]).
+///
+/// ```dart
+/// int _act = 1;
+/// // ...
+/// new ListTile(
+///   leading: const Icon(Icons.flight_land),
+///   title: const Text('Trix\'s airplane'),
+///   subtitle: _act != 2 ? const Text('The airplane is only in Act II.') : null,
+///   enabled: _act == 2,
+///   onTap: () { /* react to the tile being tapped */ }
+/// )
+/// ```
+///
 /// See also:
 ///
 ///  * [ListTileTheme], which defines visual properties for [ListTile]s.

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

@@ -130,9 +130,14 @@ class Material extends StatefulWidget {
   /// the shape is rectangular, and the default color.
   final MaterialType type;
 
-  /// The z-coordinate at which to place this material.
+  /// The z-coordinate at which to place this material. This controls the size
+  /// of the shadow below the material.
   ///
-  /// Defaults to 0.
+  /// If this is non-zero, the contents of the card are clipped, because the
+  /// widget conceptually defines an independent printed piece of material.
+  ///
+  /// Defaults to 0. Changing this value will cause the shadow to animate over
+  /// [kThemeChangeDuration].
   final double elevation;
 
   /// The color to paint the material.

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

@@ -498,7 +498,10 @@ class PopupMenuButton<T> extends StatefulWidget {
   /// used for accessibility.
   final String tooltip;
 
-  /// The z-coordinate at which to place the menu when open.
+  /// The z-coordinate at which to place the menu when open. This controls the
+  /// size of the shadow below the menu.
+  ///
+  /// Defaults to 8, the appropriate elevation for popup menus.
   final double elevation;
 
   /// Matches IconButton's 8 dps padding by default. In some cases, notably where

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

@@ -14,7 +14,7 @@ const double _kMinCircularProgressIndicatorSize = 36.0;
 
 // TODO(hansmuller): implement the support for buffer indicator
 
-/// A base class for material design progress indicators
+/// A base class for material design progress indicators.
 ///
 /// This widget cannot be instantiated directly. For a linear progress
 /// indicator, see [LinearProgressIndicator]. For a circular progress indicator,
@@ -112,7 +112,7 @@ class _LinearProgressIndicatorPainter extends CustomPainter {
   }
 }
 
-/// A material design linear progress indicator.
+/// A material design linear progress indicator, also known as a progress bar.
 ///
 /// A widget that shows progress along a line. There are two kinds of linear
 /// progress indicators:
@@ -253,7 +253,8 @@ class _CircularProgressIndicatorPainter extends CustomPainter {
   }
 }
 
-/// A material design circular progress indicator.
+/// A material design circular progress indicator, which spins to indicate that
+/// the application is busy.
 ///
 /// A widget that shows progress along a circle. There are two kinds of circular
 /// progress indicators:

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

@@ -89,7 +89,7 @@ class Radio<T> extends StatefulWidget {
   ///       _character = newValue;
   ///     });
   ///   },
-  /// ),
+  /// )
   /// ```
   final ValueChanged<T> onChanged;
 

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

@@ -62,7 +62,7 @@ import 'theme.dart';
 ///       onChanged: (SingingCharacter value) { setState(() { _character = value; }); },
 ///     ),
 ///   ],
-/// ),
+/// )
 /// ```
 ///
 /// See also:
@@ -136,7 +136,7 @@ class RadioListTile<T> extends StatelessWidget {
   ///       _character = newValue;
   ///     });
   ///   },
-  /// ),
+  /// )
   /// ```
   final ValueChanged<T> onChanged;
 

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

@@ -100,20 +100,35 @@ class RaisedButton extends StatelessWidget {
   /// value.
   final Color disabledColor;
 
-  /// The z-coordinate at which to place this button.
+  /// The z-coordinate at which to place this button. This controls the size of
+  /// the shadow below the raised button.
   ///
   /// Defaults to 2, the appropriate elevation for raised buttons.
+  ///
+  /// See also:
+  ///
+  ///  * [FlatButton], a button with no elevation.
   final double elevation;
 
-  /// The z-coordinate at which to place this button when highlighted.
+  /// The z-coordinate at which to place this button when highlighted. This
+  /// controls the size of the shadow below the raised button.
   ///
   /// Defaults to 8, the appropriate elevation for raised buttons while they are
   /// being touched.
+  ///
+  /// See also:
+  ///
+  ///  * [elevation], the default elevation.
   final double highlightElevation;
 
-  /// The z-coordinate at which to place this button when disabled.
+  /// The z-coordinate at which to place this button when disabled. This
+  /// controls the size of the shadow below the raised button.
   ///
   /// Defaults to 0, the appropriate elevation for disabled raised buttons.
+  ///
+  /// See also:
+  ///
+  ///  * [elevation], the default elevation.
   final double disabledElevation;
 
   /// The theme brightness to use for this button.

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

@@ -103,7 +103,7 @@ class Slider extends StatefulWidget {
   ///       _duelCommandment = newValue.round();
   ///     });
   ///   },
-  /// ),
+  /// )
   /// ```
   final ValueChanged<double> onChanged;
 

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

@@ -80,7 +80,7 @@ class Switch extends StatefulWidget {
   ///       _giveVerse = newValue;
   ///     });
   ///   },
-  /// ),
+  /// )
   /// ```
   final ValueChanged<bool> onChanged;
 

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

@@ -111,7 +111,7 @@ class SwitchListTile extends StatelessWidget {
   ///     });
   ///   },
   ///   title: new Text('Lights'),
-  /// ),
+  /// )
   /// ```
   final ValueChanged<bool> onChanged;
 

packages/flutter/lib/src/painting/box_painter.dart

@@ -213,7 +213,7 @@ enum BorderStyle {
 ///     ),
 ///   ),
 ///   child: new Text('Flutter in the sky', textAlign: TextAlign.center),
-/// ),
+/// )
 /// ```
 ///
 /// See also:
@@ -366,7 +366,7 @@ class BorderSide {
 ///       style: const TextStyle(color: const Color(0xFF000000))
 ///     ),
 ///   ),
-/// ),
+/// )
 /// ```
 ///
 /// See also:
@@ -809,7 +809,7 @@ abstract class Gradient {
 ///       tileMode: TileMode.repeated, // repeats the gradient over the canvas
 ///     ),
 ///   ),
-/// ),
+/// )
 /// ```
 ///
 /// See also:

packages/flutter/lib/src/painting/edge_insets.dart

@@ -21,16 +21,49 @@ enum Axis {
 ///
 /// Typically used for an offset from each of the four sides of a box. For
 /// example, the padding inside a box can be represented using this class.
+///
+/// ## Sample code
+///
+/// Here are some examples of how to create [EdgeInsets] instances:
+///
+/// ```dart
+/// // typical 8-pixel margin on all sides
+/// const EdgeInsets.all(8.0)
+///
+/// // 8-pixel margin above and below, no horizontal margins
+/// const EdgeInsets.symmetric(vertical: 8.0)
+///
+/// // left-margin indent of 40 pixels
+/// const EdgeInsets.only(left: 40.0)
+/// ```
+///
+/// See also:
+///
+///  * [Padding], a widget that describes margins using [EdgeInsets].
 @immutable
 class EdgeInsets {
   /// Creates insets from offsets from the left, top, right, and bottom.
   const EdgeInsets.fromLTRB(this.left, this.top, this.right, this.bottom);
 
   /// Creates insets where all the offsets are value.
+  ///
+  /// ## Sample code
+  ///
+  /// ```dart
+  /// // typical 8-pixel margin on all sides
+  /// const EdgeInsets.all(8.0)
+  /// ```
   const EdgeInsets.all(double value)
       : left = value, top = value, right = value, bottom = value;
 
   /// Creates insets with only the given values non-zero.
+  ///
+  /// ## Sample code
+  ///
+  /// ```dart
+  /// // left-margin indent of 40 pixels
+  /// const EdgeInsets.only(left: 40.0)
+  /// ```
   const EdgeInsets.only({
     this.left: 0.0,
     this.top: 0.0,
@@ -39,11 +72,23 @@ class EdgeInsets {
   });
 
   /// Creates insets with symmetrical vertical and horizontal offsets.
+  ///
+  /// ## Sample code
+  ///
+  /// ```dart
+  /// // 8-pixel margin above and below, no horizontal margins
+  /// const EdgeInsets.symmetric(vertical: 8.0)
+  /// ```
   const EdgeInsets.symmetric({ double vertical: 0.0,
                              double horizontal: 0.0 })
     : left = horizontal, top = vertical, right = horizontal, bottom = vertical;
 
   /// Creates insets that match the given window padding.
+  ///
+  /// If you need the current system padding in the context of a widget,
+  /// consider using [MediaQuery.of] to obtain the current padding rather than
+  /// using the value from [ui.window], so that you get notified when it
+  /// changes.
   EdgeInsets.fromWindowPadding(ui.WindowPadding padding, double devicePixelRatio)
     : left = padding.left / devicePixelRatio,
       top = padding.top / devicePixelRatio,

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

@@ -8,12 +8,23 @@ import 'box.dart';
 import 'object.dart';
 
 /// How the child is inscribed into the available space.
+///
+/// See also:
+///
+///  * [RenderFlex], the flex render object.
+///  * [Column], [Row], and [Flex], the flex widgets.
+///  * [Expanded], the widget equivalent of [tight].
+///  * [Flexible], the widget equivalent of [loose].
 enum FlexFit {
   /// The child is forced to fill the available space.
+  ///
+  /// The [Expanded] widget assigns this kind of [FlexFit] to its child.
   tight,
 
   /// The child can be at most as large as the available space (but is
   /// allowed to be smaller).
+  ///
+  /// The [Flexible] widget assigns this kind of [FlexFit] to its child.
   loose,
 }
 
@@ -47,7 +58,13 @@ class FlexParentData extends ContainerBoxParentDataMixin<RenderBox> {
 /// This value controls whether to maximize or minimize the amount of free
 /// space, subject to the incoming layout constraints.
 ///
-/// See [Row], [Column], [MainAxisAlignment], [Flexible].
+/// See also:
+///
+///  * [Column], [Row], and [Flex], the flex widgets.
+///  * [Expanded] and [Flexible], the widgets that controls a flex widgets'
+///    children's flex.
+///  * [RenderFlex], the flex render object.
+///  * [MainAxisAlignment], which controls how the free space is distributed.
 enum MainAxisSize {
   /// Minimize the amount of free space along the main axis, subject to the
   /// incoming layout constraints.
@@ -67,6 +84,11 @@ enum MainAxisSize {
 }
 
 /// How the children should be placed along the main axis in a flex layout.
+///
+/// See also:
+///
+///  * [Column], [Row], and [Flex], the flex widgets.
+///  * [RenderFlex], the flex render object.
 enum MainAxisAlignment {
   /// Place the children as close to the start of the main axis as possible.
   start,
@@ -90,20 +112,41 @@ enum MainAxisAlignment {
 }
 
 /// How the children should be placed along the cross axis in a flex layout.
+///
+/// See also:
+///
+///  * [Column], [Row], and [Flex], the flex widgets.
+///  * [RenderFlex], the flex render object.
 enum CrossAxisAlignment {
-  /// Place the children as close to the start of the cross axis as possible.
+  /// Place the children with their start edge aligned with the start side of
+  /// the cross axis.
+  ///
+  /// For example, in a column (a flex with a vertical axis), this aligns the
+  /// left edge of the children along the left edge of the column.
   start,
 
   /// Place the children as close to the end of the cross axis as possible.
+  ///
+  /// For example, in a column (a flex with a vertical axis), this aligns the
+  /// right edge of the children along the right edge of the column.
   end,
 
-  /// Place the children as close to the middle of the cross axis as possible.
+  /// Place the children so that their centers align with the middle of the
+  /// cross axis.
+  ///
+  /// This is the default cross-axis alignment.
   center,
 
   /// Require the children to fill the cross axis.
+  ///
+  /// This causes the constraints passed to the children to be tight in the
+  /// cross axis.
   stretch,
 
   /// Place the children along the cross axis such that their baselines match.
+  ///
+  /// If the main axis is vertical, then this value is treated like [start]
+  /// (since baselines are always horizontal).
   baseline,
 }
 

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

@@ -325,7 +325,7 @@ typedef Widget AsyncWidgetBuilder<T>(BuildContext context, AsyncSnapshot<T> snap
 ///       default: throw "Unknown: ${snapshot.connectionState}";
 ///     }
 ///   },
-/// ),
+/// )
 /// ```
 class StreamBuilder<T> extends StreamBuilderBase<T, AsyncSnapshot<T>> {
   /// Creates a new [StreamBuilder] that builds itself based on the latest
@@ -424,7 +424,7 @@ class StreamBuilder<T> extends StreamBuilderBase<T, AsyncSnapshot<T>> {
 ///           return new Text('Result: ${snapshot.data}');
 ///     }
 ///   },
-/// ),
+/// )
 /// ```
 class FutureBuilder<T> extends StatefulWidget {
   /// Creates a widget that builds itself based on the latest snapshot of

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

@@ -217,7 +217,7 @@ class BackdropFilter extends SingleChildRenderObjectWidget {
 ///       ),
 ///     ),
 ///   ),
-/// ),
+/// )
 /// ```
 ///
 /// See also:
@@ -285,7 +285,7 @@ class CustomPaint extends SingleChildRenderObjectWidget {
 ///  * [OverflowBox]
 ///  * [SizedOverflowBox]
 ///
-/// ## Example
+/// ## Sample code
 ///
 /// For example, use a clip to show the top half of an [Image], you can use a
 /// [ClipRect] combined with an [Align]:
@@ -297,7 +297,7 @@ class CustomPaint extends SingleChildRenderObjectWidget {
 ///     heightFactor: 0.5,
 ///     child: new Image(...),
 ///   ),
-/// ),
+/// )
 /// ```
 ///
 /// See also:
@@ -1096,7 +1096,8 @@ class ConstrainedBox extends SingleChildRenderObjectWidget {
 }
 
 /// A widget that sizes its child to a fraction of the total available space.
-/// For more details about the layout algorithm, see [RenderFractionallySizedOverflowBox].
+/// For more details about the layout algorithm, see
+/// [RenderFractionallySizedOverflowBox].
 ///
 /// See also:
 ///
@@ -2023,6 +2024,8 @@ class Positioned extends ParentDataWidget<Stack> {
 ///
 /// ## Layout algorithm
 ///
+/// _This section describes how a [Flex] is rendered by the framework._
+///
 /// Layout for a [Flex] proceeds in six steps:
 ///
 /// 1. Layout each child a null or zero flex factor (e.g., those that are not
@@ -2055,6 +2058,14 @@ class Positioned extends ParentDataWidget<Stack> {
 ///    [mainAxisAlignment] is [MainAxisAlignment.spaceBetween], any main axis
 ///    space that has not been allocated to children is divided evenly and
 ///    placed between the children.
+///
+/// See also:
+///
+///  * [Row], for a version of this widget that is always horizontal.
+///  * [Column], for a version of this widget that is always vertical.
+///  * [Expanded], to indicate children that should take all the remaining room.
+///  * [Flexible], to indicate children that should share the remaining room but
+///    that may be sized smaller (leaving some remaining room unused).
 class Flex extends MultiChildRenderObjectWidget {
   /// Creates a flex layout.
   ///
@@ -2152,8 +2163,35 @@ class Flex extends MultiChildRenderObjectWidget {
 /// If you only have one child, then consider using [Align] or [Center] to
 /// position the child.
 ///
+/// ## Sample code
+///
+/// This example divides the available space into three (horizontally), and
+/// places text centered in the first two cells and the Flutter logo centered in
+/// the third:
+///
+/// ```dart
+/// new Row(
+///   children: <Widget>[
+///     new Expanded(
+///       child: new Text('Deliver features faster', textAlign: TextAlign.center),
+///     ),
+///     new Expanded(
+///       child: new Text('Craft beautiful UIs', textAlign: TextAlign.center),
+///     ),
+///     new Expanded(
+///       child: new FittedBox(
+///         fit: BoxFit.contain, // otherwise the logo will be tiny
+///         child: const FlutterLogo(),
+///       ),
+///     ),
+///   ],
+/// )
+/// ```
+///
 /// ## Layout algorithm
 ///
+/// _This section describes how a [Row] is rendered by the framework._
+///
 /// Layout for a [Row] proceeds in six steps:
 ///
 /// 1. Layout each child a null or zero flex factor (e.g., those that are not
@@ -2184,6 +2222,15 @@ class Flex extends MultiChildRenderObjectWidget {
 ///    [mainAxisAlignment] is [MainAxisAlignment.spaceBetween], any horizontal
 ///    space that has not been allocated to children is divided evenly and
 ///    placed between the children.
+///
+/// See also:
+///
+///  * [Column], for a vertical equivalent.
+///  * [Flex], if you don't know in advance if you want a horizontal or vertical
+///    arrangement.
+///  * [Expanded], to indicate children that should take all the remaining room.
+///  * [Flexible], to indicate children that should share the remaining room but
+///    that may by sized smaller (leaving some remaining room unused).
 class Row extends Flex {
   /// Creates a horizontal array of children.
   ///
@@ -2223,8 +2270,52 @@ class Row extends Flex {
 /// If you only have one child, then consider using [Align] or [Center] to
 /// position the child.
 ///
+/// ## Sample code
+///
+/// This example uses a [Column] to arrange three widgets vertically, the last
+/// being made to fill all the remaining space.
+///
+/// ```dart
+/// new Column(
+///   children: <Widget>[
+///     new Text('Deliver features faster'),
+///     new Text('Craft beautiful UIs'),
+///     new Expanded(
+///       child: new FittedBox(
+///         fit: BoxFit.contain,
+///         child: const FlutterLogo(),
+///       ),
+///     ),
+///   ],
+/// )
+/// ```
+///
+/// In the sample above, the text and the logo are centered on each line. In the
+/// following example, the [crossAxisAlignment] is set to
+/// [CrossAxisAlignment.start], so that the children are left-aligned. The
+/// [mainAxisSize] is set to [MainAxisSize.min], so that the column shrinks to
+/// fit the children.
+///
+/// ```dart
+/// new Column(
+///   crossAxisAlignment: CrossAxisAlignment.start,
+///   mainAxisSize: MainAxisSize.min,
+///   children: <Widget>[
+///     new Text('We move under cover and we move as one'),
+///     new Text('Through the night, we have one shot to live another day'),
+///     new Text('We cannot let a stray gunshot give us away'),
+///     new Text('We will fight up close, seize the moment and stay in it'),
+///     new Text('It’s either that or meet the business end of a bayonet'),
+///     new Text('The code word is ‘Rochambeau,’ dig me?'),
+///     new Text('Rochambeau!', style: DefaultTextStyle.of(context).style.apply(fontSizeFactor: 2.0)),
+///   ],
+/// )
+/// ```
+///
 /// ## Layout algorithm
 ///
+/// _This section describes how a [Column] is rendered by the framework._
+///
 /// Layout for a [Column] proceeds in six steps:
 ///
 /// 1. Layout each child a null or zero flex factor (e.g., those that are not
@@ -2257,6 +2348,15 @@ class Row extends Flex {
 ///    [mainAxisAlignment] is [MainAxisAlignment.spaceBetween], any vertical
 ///    space that has not been allocated to children is divided evenly and
 ///    placed between the children.
+///
+/// See also:
+///
+///  * [Row], for a horizontal equivalent.
+///  * [Flex], if you don't know in advance if you want a horizontal or vertical
+///    arrangement.
+///  * [Expanded], to indicate children that should take all the remaining room.
+///  * [Flexible], to indicate children that should share the remaining room but
+///    that may size smaller (leaving some remaining room unused).
 class Column extends Flex {
   /// Creates a vertical array of children.
   ///
@@ -2651,7 +2751,7 @@ class Flow extends MultiChildRenderObjectWidget {
 ///       new TextSpan(text: ' world!'),
 ///     ],
 ///   ),
-/// ),
+/// )
 /// ```
 ///
 /// See also:

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

@@ -34,7 +34,7 @@ import 'image.dart';
 ///       stops: <double>[0.9, 1.0],
 ///     ),
 ///   ),
-/// ),
+/// )
 /// ```
 ///
 /// See also:

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

@@ -235,6 +235,55 @@ abstract class ScrollView extends StatelessWidget {
 /// list and a grid, use a list of three slivers: [SliverAppBar], [SliverList],
 /// and [SliverGrid].
 ///
+/// ## Sample code
+///
+/// This sample code shows a scroll view that contains a flexible pinned app
+/// bar, a grid, and an infinite list.
+///
+/// ```dart
+/// new CustomScrollView(
+///   slivers: <Widget>[
+///     const SliverAppBar(
+///       pinned: true,
+///       expandedHeight: 250.0,
+///       flexibleSpace: const FlexibleSpaceBar(
+///         title: const Text('Demo'),
+///       ),
+///     ),
+///     new SliverGrid(
+///       gridDelegate: new SliverGridDelegateWithMaxCrossAxisExtent(
+///         maxCrossAxisExtent: 200.0,
+///         mainAxisSpacing: 10.0,
+///         crossAxisSpacing: 10.0,
+///         childAspectRatio: 4.0,
+///       ),
+///       delegate: new SliverChildBuilderDelegate(
+///         (BuildContext context, int index) {
+///           return new Container(
+///             alignment: FractionalOffset.center,
+///             color: Colors.teal[100 * (index % 9)],
+///             child: new Text('grid item $index'),
+///           );
+///         },
+///         childCount: 20,
+///       ),
+///     ),
+///     new SliverFixedExtentList(
+///       itemExtent: 50.0,
+///       delegate: new SliverChildBuilderDelegate(
+///         (BuildContext context, int index) {
+///           return new Container(
+///             alignment: FractionalOffset.center,
+///             color: Colors.lightBlue[100 * (index % 9)],
+///             child: new Text('list item $index'),
+///           );
+///         },
+///       ),
+///     ),
+///   ],
+/// )
+/// ```
+///
 /// See also:
 ///
 ///  * [SliverList], which is a sliver that displays linear list of children.
@@ -329,7 +378,7 @@ abstract class BoxScrollView extends ScrollView {
   }
 }
 
-/// A scrollable, linear list of widgets.
+/// A scrollable list of widgets arranged linearly.
 ///
 /// [ListView] is the most commonly used scrolling widget. It displays its
 /// children one after another in the scroll direction. In the cross axis, the
@@ -359,6 +408,20 @@ abstract class BoxScrollView extends ScrollView {
 ///     a [SliverChildDelegate] can control the algorithm used to estimate the
 ///     size of children that are not actually visible.
 ///
+/// ## Sample code
+///
+/// An infinite list of children:
+///
+/// ```dart
+/// new ListView.builder(
+///   padding: new EdgeInsets.all(8.0),
+///   itemExtent: 20.0,
+///   itemBuilder: (BuildContext context, int index) {
+///     return new Text('entry $index');
+///   },
+/// )
+/// ```
+///
 /// See also:
 ///
 ///  * [SingleChildScrollView], which is a scrollable widget that has a single
@@ -368,6 +431,8 @@ abstract class BoxScrollView extends ScrollView {
 ///  * [GridView], which is scrollable, 2D array of widgets.
 ///  * [CustomScrollView], which is a scrollable widget that creates custom
 ///    scroll effects using slivers.
+///  * [ListBody], which arranges its children in a similar manner, but without
+///    scrolling.
 class ListView extends BoxScrollView {
   /// Creates a scrollable, linear array of widgets from an explicit [List].
   ///

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

@@ -334,6 +334,26 @@ class SliverList extends SliverMultiBoxAdaptorWidget {
 /// [SliverFixedExtentList] does not need to perform layout on its children to
 /// obtain their extent in the main axis.
 ///
+/// ## Sample code
+///
+/// This example, which would be inserted into a [CustomScrollView.slivers]
+/// list, shows an infinite number of items in varying shades of blue:
+///
+/// ```dart
+/// new SliverFixedExtentList(
+///   itemExtent: 50.0,
+///   delegate: new SliverChildBuilderDelegate(
+///     (BuildContext context, int index) {
+///       return new Container(
+///         alignment: FractionalOffset.center,
+///         color: Colors.lightBlue[100 * (index % 9)],
+///         child: new Text('list item $index'),
+///       );
+///     },
+///   ),
+/// )
+/// ```
+///
 /// See also:
 ///
 ///  * [SliverPrototypeExtentList], which is similar to [SliverFixedExtentList]
@@ -373,6 +393,32 @@ class SliverFixedExtentList extends SliverMultiBoxAdaptorWidget {
 /// [gridDelegate]. Each child is forced to have the size specified by the
 /// [gridDelegate].
 ///
+/// ## Sample code
+///
+/// This example, which would be inserted into a [CustomScrollView.slivers]
+/// list, shows twenty boxes in a pretty teal grid:
+///
+/// ```dart
+/// new SliverGrid(
+///   gridDelegate: new SliverGridDelegateWithMaxCrossAxisExtent(
+///     maxCrossAxisExtent: 200.0,
+///     mainAxisSpacing: 10.0,
+///     crossAxisSpacing: 10.0,
+///     childAspectRatio: 4.0,
+///   ),
+///   delegate: new SliverChildBuilderDelegate(
+///     (BuildContext context, int index) {
+///       return new Container(
+///         alignment: FractionalOffset.center,
+///         color: Colors.teal[100 * (index % 9)],
+///         child: new Text('grid item $index'),
+///       );
+///     },
+///     childCount: 20,
+///   ),
+/// )
+/// ```
+///
 /// See also:
 ///
 ///  * [SliverList], which places its children in a linear array.