Complete dartdocs for rendering.dart (#4316)

All of the public APIs in rendering.dart now have dartdocs.

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

@@ -118,6 +118,9 @@ class PictureLayer extends Layer {
 
 /// (mojo-only) A layer that represents content from another process.
 class ChildSceneLayer extends Layer {
+  /// Creates a layer that displays content rendered by another process.
+  ///
+  /// All of the arguments must not be null.
   ChildSceneLayer({
     this.offset,
     this.devicePixelRatio,
@@ -126,10 +129,19 @@ class ChildSceneLayer extends Layer {
     this.sceneToken
   });
 
+  /// Offset from parent in the parent's coordinate system.
   Offset offset;
+
+  /// The number of physical pixels the child should produce for each logical pixel.
   double devicePixelRatio;
+
+  /// The horizontal extent of the child, in physical pixels.
   int physicalWidth;
+
+  /// The vertical extent of the child, in physical pixels.
   int physicalHeight;
+
+  /// The composited scene that will contain the content rendered by the child.
   mojom.SceneToken sceneToken;
 
   @override

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

@@ -1988,6 +1988,9 @@ class RenderMetaData extends RenderProxyBoxWithHitTestBehavior {
 /// Listens for the specified gestures from the semantics server (e.g.
 /// an accessibility tool).
 class RenderSemanticsGestureHandler extends RenderProxyBox implements SemanticActionHandler {
+  /// Creates a render object that listens for specific semantic gestures.
+  ///
+  /// The [scrollFactor] argument must not be null.
   RenderSemanticsGestureHandler({
     RenderBox child,
     GestureTapCallback onTap,
@@ -2001,6 +2004,7 @@ class RenderSemanticsGestureHandler extends RenderProxyBox implements SemanticAc
        _onVerticalDragUpdate = onVerticalDragUpdate,
        super(child);
 
+   /// Called when the user taps on the render object.
   GestureTapCallback get onTap => _onTap;
   GestureTapCallback _onTap;
   set onTap(GestureTapCallback value) {
@@ -2013,6 +2017,7 @@ class RenderSemanticsGestureHandler extends RenderProxyBox implements SemanticAc
       markNeedsSemanticsUpdate(onlyChanges: hasSemantics == didHaveSemantics);
   }
 
+  /// Called when the user presses on the render object for a long period of time.
   GestureLongPressCallback get onLongPress => _onLongPress;
   GestureLongPressCallback _onLongPress;
   set onLongPress(GestureLongPressCallback value) {
@@ -2025,6 +2030,7 @@ class RenderSemanticsGestureHandler extends RenderProxyBox implements SemanticAc
       markNeedsSemanticsUpdate(onlyChanges: hasSemantics == didHaveSemantics);
   }
 
+  /// Called when the user scrolls to the left or to the right.
   GestureDragUpdateCallback get onHorizontalDragUpdate => _onHorizontalDragUpdate;
   GestureDragUpdateCallback _onHorizontalDragUpdate;
   set onHorizontalDragUpdate(GestureDragUpdateCallback value) {
@@ -2037,6 +2043,7 @@ class RenderSemanticsGestureHandler extends RenderProxyBox implements SemanticAc
       markNeedsSemanticsUpdate(onlyChanges: hasSemantics == didHaveSemantics);
   }
 
+  /// Called when the user scrolls up or down.
   GestureDragUpdateCallback get onVerticalDragUpdate => _onVerticalDragUpdate;
   GestureDragUpdateCallback _onVerticalDragUpdate;
   set onVerticalDragUpdate(GestureDragUpdateCallback value) {
@@ -2113,8 +2120,11 @@ class RenderSemanticsGestureHandler extends RenderProxyBox implements SemanticAc
   }
 }
 
-/// Add annotations to the SemanticsNode for this subtree.
+/// Add annotations to the [SemanticsNode] for this subtree.
 class RenderSemanticAnnotations extends RenderProxyBox {
+  /// Creates a render object that attaches a semantic annotation.
+  ///
+  /// The [container] argument must not be null.
   RenderSemanticAnnotations({
     RenderBox child,
     bool container: false,
@@ -2197,6 +2207,7 @@ class RenderSemanticAnnotations extends RenderProxyBox {
 /// form part of a single conceptual widget, e.g. a checkbox, a label,
 /// and the gesture detector that goes with them.
 class RenderMergeSemantics extends RenderProxyBox {
+  /// Creates a render object that merges the semantics from its descendants.
   RenderMergeSemantics({ RenderBox child }) : super(child);
 
   @override
@@ -2210,6 +2221,7 @@ class RenderMergeSemantics extends RenderProxyBox {
 /// Useful e.g. for hiding text that is redundant with other text next
 /// to it (e.g. text included only for the visual effect).
 class RenderExcludeSemantics extends RenderProxyBox {
+  /// Creates a render object that ignores the semantics of its subtree.
   RenderExcludeSemantics({ RenderBox child }) : super(child);
 
   @override

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

@@ -5,6 +5,8 @@
 import 'dart:math' as math;
 import 'dart:ui' show lerpDouble, hashValues;
 
+import 'package:meta/meta.dart';
+
 import 'box.dart';
 import 'object.dart';
 
@@ -197,10 +199,50 @@ class StackParentData extends ContainerBoxParentDataMixin<RenderBox> {
   }
 }
 
-abstract class RenderStackBase extends RenderBox
+/// Implements the stack layout algorithm
+///
+/// In a stack layout, the children are positioned on top of each other in the
+/// order in which they appear in the child list. First, the non-positioned
+/// children (those with null values for top, right, bottom, and left) are
+/// laid out and initially placed in the upper-left corner of the stack. The
+/// stack is then sized to enclose all of the non-positioned children. If there
+/// are no non-positioned children, the stack becomes as large as possible.
+///
+/// The final location of non-positioned children is determined by the alignment
+/// parameter. The left of each non-positioned child becomes the
+/// difference between the child's width and the stack's width scaled by
+/// alignment.x. The top of each non-positioned child is computed
+/// similarly and scaled by alignment.y. So if the alignment x and y properties
+/// are 0.0 (the default) then the non-positioned children remain in the
+/// upper-left corner. If the alignment x and y properties are 0.5 then the
+/// non-positioned children are centered within the stack.
+///
+/// Next, the positioned children are laid out. If a child has top and bottom
+/// values that are both non-null, the child is given a fixed height determined
+/// by subtracting the sum of the top and bottom values from the height of the stack.
+/// Similarly, if the child has right and left values that are both non-null,
+/// the child is given a fixed width derived from the stack's width.
+/// Otherwise, the child is given unbounded constraints in the non-fixed dimensions.
+///
+/// Once the child is laid out, the stack positions the child
+/// according to the top, right, bottom, and left properties of their
+/// [StackParentData]. For example, if the bottom value is 10.0, the
+/// bottom edge of the child will be inset 10.0 pixels from the bottom
+/// edge of the stack. If the child extends beyond the bounds of the
+/// stack, the stack will clip the child's painting to the bounds of
+/// the stack.
+///
+/// See also:
+///
+///  * [RenderFlow]
+class RenderStack extends RenderBox
     with ContainerRenderObjectMixin<RenderBox, StackParentData>,
          RenderBoxContainerDefaultsMixin<RenderBox, StackParentData> {
-  RenderStackBase({
+  /// Creates a stack render object.
+  ///
+  /// By default, the non-positioned children of the stack are aligned by their
+  /// top left corners.
+  RenderStack({
     List<RenderBox> children,
     FractionalOffset alignment: FractionalOffset.topLeft
   }) : _alignment = alignment {
@@ -215,6 +257,12 @@ abstract class RenderStackBase extends RenderBox
       child.parentData = new StackParentData();
   }
 
+  /// How to align the non-positioned children in the stack.
+  ///
+  /// The non-positioned children are placed relative to each other such that
+  /// the points determined by [alignment] are co-located. For example, if the
+  /// [alignment] is [FractionalOffset.topLeft], then the top left corner of
+  /// each non-positioned child will be located at the same global coordinate.
   FractionalOffset get alignment => _alignment;
   FractionalOffset _alignment;
   set alignment (FractionalOffset value) {
@@ -350,7 +398,14 @@ abstract class RenderStackBase extends RenderBox
     return defaultHitTestChildren(result, position: position);
   }
 
-  void paintStack(PaintingContext context, Offset offset);
+  /// Override in subclasses to customize how the stack paints.
+  ///
+  /// By default, the stack uses [defaultPaint]. This function is called by
+  /// [paint] after potentially applying a clip to contain visual overflow.
+  @protected
+  void paintStack(PaintingContext context, Offset offset) {
+    defaultPaint(context, offset);
+  }
 
   @override
   void paint(PaintingContext context, Offset offset) {
@@ -365,63 +420,15 @@ abstract class RenderStackBase extends RenderBox
   Rect describeApproximatePaintClip(RenderObject child) => _hasVisualOverflow ? Point.origin & size : null;
 }
 
-/// Implements the stack layout algorithm
-///
-/// In a stack layout, the children are positioned on top of each other in the
-/// order in which they appear in the child list. First, the non-positioned
-/// children (those with null values for top, right, bottom, and left) are
-/// laid out and initially placed in the upper-left corner of the stack. The
-/// stack is then sized to enclose all of the non-positioned children. If there
-/// are no non-positioned children, the stack becomes as large as possible.
-///
-/// The final location of non-positioned children is determined by the alignment
-/// parameter. The left of each non-positioned child becomes the
-/// difference between the child's width and the stack's width scaled by
-/// alignment.x. The top of each non-positioned child is computed
-/// similarly and scaled by alignment.y. So if the alignment x and y properties
-/// are 0.0 (the default) then the non-positioned children remain in the
-/// upper-left corner. If the alignment x and y properties are 0.5 then the
-/// non-positioned children are centered within the stack.
-///
-/// Next, the positioned children are laid out. If a child has top and bottom
-/// values that are both non-null, the child is given a fixed height determined
-/// by subtracting the sum of the top and bottom values from the height of the stack.
-/// Similarly, if the child has right and left values that are both non-null,
-/// the child is given a fixed width derived from the stack's width.
-/// Otherwise, the child is given unbounded constraints in the non-fixed dimensions.
-///
-/// Once the child is laid out, the stack positions the child
-/// according to the top, right, bottom, and left properties of their
-/// [StackParentData]. For example, if the bottom value is 10.0, the
-/// bottom edge of the child will be inset 10.0 pixels from the bottom
-/// edge of the stack. If the child extends beyond the bounds of the
-/// stack, the stack will clip the child's painting to the bounds of
-/// the stack.
-///
-/// See also:
-///
-///  * [RenderFlow]
-class RenderStack extends RenderStackBase {
-  RenderStack({
-    List<RenderBox> children,
-    FractionalOffset alignment: FractionalOffset.topLeft
-  }) : super(
-   children: children,
-   alignment: alignment
- );
-
-  @override
-  void paintStack(PaintingContext context, Offset offset) {
-    defaultPaint(context, offset);
-  }
-}
-
 /// Implements the same layout algorithm as RenderStack but only paints the child
 /// specified by index.
 ///
 /// Although only one child is displayed, the cost of the layout algorithm is
 /// still O(N), like an ordinary stack.
-class RenderIndexedStack extends RenderStackBase {
+class RenderIndexedStack extends RenderStack {
+  /// Creates a stack render object that paints a single child.
+  ///
+  /// The [index] argument must not be null.
   RenderIndexedStack({
     List<RenderBox> children,
     FractionalOffset alignment: FractionalOffset.topLeft,
@@ -433,6 +440,7 @@ class RenderIndexedStack extends RenderStackBase {
     assert(index != null);
   }
 
+  /// The index of the child to show.
   int get index => _index;
   int _index;
   set index (int value) {

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

@@ -76,6 +76,9 @@ abstract class TableColumnWidth {
 /// column will participate in the distribution of remaining space
 /// once all the non-flexible columns have been sized.
 class IntrinsicColumnWidth extends TableColumnWidth {
+  /// Creates a column width based on intrinsic sizing.
+  ///
+  /// This sizing algorithm is very expensive.
   const IntrinsicColumnWidth({ double flex }) : _flex = flex;
 
   @override
@@ -104,7 +107,12 @@ class IntrinsicColumnWidth extends TableColumnWidth {
 ///
 /// This is the cheapest way to size a column.
 class FixedColumnWidth extends TableColumnWidth {
+  /// Creates a column width based on a fixed number of logical pixels.
+  ///
+  /// The [value] argument must not be null.
   const FixedColumnWidth(this.value);
+
+  /// The width the column should occupy in logical pixels.
   final double value;
 
   @override
@@ -125,7 +133,14 @@ class FixedColumnWidth extends TableColumnWidth {
 ///
 /// This is a cheap way to size a column.
 class FractionColumnWidth extends TableColumnWidth {
+  /// Creates a column width based on a fraction of the table's constraints'
+  /// maxWidth.
+  ///
+  /// The [value] argument must not be null.
   const FractionColumnWidth(this.value);
+
+  /// The fraction of the table's constraints' maxWidth that this column should
+  /// occupy.
   final double value;
 
   @override
@@ -154,7 +169,14 @@ class FractionColumnWidth extends TableColumnWidth {
 ///
 /// This is a cheap way to size a column.
 class FlexColumnWidth extends TableColumnWidth {
+  /// Creates a column width based on a fraction of the remaining space once all
+  /// the other columns have been laid out.
+  ///
+  /// The [value] argument must not be null.
   const FlexColumnWidth([this.value = 1.0]);
+
+  /// The reaction of the of the remaining space once all the other columns have
+  /// been laid out that this column should occupy.
   final double value;
 
   @override
@@ -187,8 +209,13 @@ class FlexColumnWidth extends TableColumnWidth {
 /// Both specifications are evaluated, so if either specification is
 /// expensive, so is this.
 class MaxColumnWidth extends TableColumnWidth {
+  /// Creates a column width that is the maximum of two other column widths.
   const MaxColumnWidth(this.a, this.b);
+
+  /// A lower bound for the width of this column.
   final TableColumnWidth a;
+
+  /// Another lower bound for the width of this column.
   final TableColumnWidth b;
 
   @override
@@ -233,8 +260,13 @@ class MaxColumnWidth extends TableColumnWidth {
 /// Both specifications are evaluated, so if either specification is
 /// expensive, so is this.
 class MinColumnWidth extends TableColumnWidth {
-  const MinColumnWidth(this.a, this.b); // at most as big as a or b
+  /// Creates a column width that is the minimum of two other column widths.
+  const MinColumnWidth(this.a, this.b);
+
+  /// An upper bound for the width of this column.
   final TableColumnWidth a;
+
+  /// Another upper bound for the width of this column.
   final TableColumnWidth b;
 
   @override
@@ -273,6 +305,9 @@ class MinColumnWidth extends TableColumnWidth {
 /// This is like [Border], with the addition of two sides: the inner
 /// horizontal borders and the inner vertical borders.
 class TableBorder extends Border {
+  /// Creates a border for a table.
+  ///
+  /// All the sides of the border default to [BorderSide.none].
   const TableBorder({
     BorderSide top: BorderSide.none,
     BorderSide right: BorderSide.none,
@@ -287,6 +322,7 @@ class TableBorder extends Border {
     left: left
   );
 
+  /// A uniform border with all sides the same color and width.
   factory TableBorder.all({
     Color color: const Color(0xFF000000),
     double width: 1.0
@@ -295,6 +331,8 @@ class TableBorder extends Border {
     return new TableBorder(top: side, right: side, bottom: side, left: side, horizontalInside: side, verticalInside: side);
   }
 
+  /// Creates a border for a table where all the interior sides use the same
+  /// styling and all the exterior sides use the same styling.
   factory TableBorder.symmetric({
     BorderSide inside: BorderSide.none,
     BorderSide outside: BorderSide.none
@@ -309,10 +347,37 @@ class TableBorder extends Border {
     );
   }
 
+  /// The horizontal interior sides of this border.
   final BorderSide horizontalInside;
 
+  /// The vertical interior sides of this border.
   final BorderSide verticalInside;
 
+  @override
+  bool get isUniform {
+    assert(horizontalInside != null);
+    assert(verticalInside != null);
+    if (!super.isUniform)
+      return false;
+
+    final Color topColor = top.color;
+    if (horizontalInside.color != topColor ||
+        verticalInside.color != topColor)
+      return false;
+
+    final double topWidth = top.width;
+    if (horizontalInside.width != topWidth ||
+        verticalInside.width != topWidth)
+      return false;
+
+    final BorderStyle topStyle = top.style;
+    if (horizontalInside.style != topStyle ||
+        verticalInside.style != topStyle)
+      return false;
+
+    return true;
+  }
+
   @override
   TableBorder scale(double t) {
     return new TableBorder(
@@ -325,6 +390,7 @@ class TableBorder extends Border {
     );
   }
 
+  /// Linearly interpolate between two table borders.
   static TableBorder lerp(TableBorder a, TableBorder b, double t) {
     if (a == null && b == null)
       return null;
@@ -376,6 +442,9 @@ enum TableCellVerticalAlignment {
   /// baseline. Cells with no baseline are top-aligned instead. The baseline
   /// used is specified by [RenderTable.baseline]. It is not valid to use the
   /// baseline value if [RenderTable.baseline] is not specified.
+  ///
+  /// This vertial alignment is relatively expensive because it causes the table
+  /// to compute the baseline for each cell in the row.
   baseline,
 
   /// Cells with this alignment are sized to be as tall as the row, then made to fit the row.
@@ -385,6 +454,17 @@ enum TableCellVerticalAlignment {
 
 /// A table where the columns and rows are sized to fit the contents of the cells.
 class RenderTable extends RenderBox {
+  /// Creates a table render object.
+  ///
+  ///  * `columns` must either be null or non-negative. If `columns` is null,
+  ///    the number of columns will be inferred from length of the first sublist
+  ///    of `children`.
+  ///  * `rows` must either be null or non-negative. If `rows` is null, the
+  ///    number of rows will be inferred from the `children`. If `rows` is not
+  ///    null, then `children` must be null.
+  ///  * `children` must either be null or contain lists of all the same length.
+  ///    if `children` is not null, then `rows` must be null.
+  ///  * [defaultColumnWidth] must not be null.
   RenderTable({
     int columns,
     int rows,
@@ -420,6 +500,13 @@ class RenderTable extends RenderBox {
   // _children.length must be rows * columns
   List<RenderBox> _children = const <RenderBox>[];
 
+  /// The number of vertical alignment lines in this table.
+  ///
+  /// Changing the number of columns will remove any children that no longer fit
+  /// in the table.
+  ///
+  /// Changing the number of columns is an expensive operation because the table
+  /// needs to rearranage its internal representation.
   int get columns => _columns;
   int _columns;
   set columns(int value) {
@@ -448,6 +535,10 @@ class RenderTable extends RenderBox {
     markNeedsLayout();
   }
 
+  /// The number of horizontal alignment lines in this table.
+  ///
+  /// Changing the number of rows will remove any children that no longer fit
+  /// in the table.
   int get rows => _rows;
   int _rows;
   set rows(int value) {
@@ -466,6 +557,15 @@ class RenderTable extends RenderBox {
     markNeedsLayout();
   }
 
+  /// How the horizontal extents of the columns of this table should be determined.
+  ///
+  /// If the [Map] has a null entry for a given column, the table uses the
+  /// [defaultColumnWidth] instead.
+  ///
+  /// The layout performance of the table depends critically on which column
+  /// sizing algorithms are used here. In particular, [IntrinsicColumnWidth] is
+  /// quite expensive because it needs to measure each cell in the column to
+  /// determine the intrinsic size of the column.
   Map<int, TableColumnWidth> get columnWidths => new Map<int, TableColumnWidth>.unmodifiable(_columnWidths);
   Map<int, TableColumnWidth> _columnWidths;
   set columnWidths(Map<int, TableColumnWidth> value) {
@@ -476,6 +576,7 @@ class RenderTable extends RenderBox {
     markNeedsLayout();
   }
 
+  /// Determines how the width of column with the given index is determined.
   void setColumnWidth(int column, TableColumnWidth value) {
     if (_columnWidths[column] == value)
       return;
@@ -483,6 +584,10 @@ class RenderTable extends RenderBox {
     markNeedsLayout();
   }
 
+  /// How to determine with widths of columns that don't have an explicit sizing algorithm.
+  ///
+  /// Specifically, the [defaultColumnWidth] is used for column `i` if
+  /// `columnWidths[i]` is null.
   TableColumnWidth get defaultColumnWidth => _defaultColumnWidth;
   TableColumnWidth _defaultColumnWidth;
   set defaultColumnWidth(TableColumnWidth value) {
@@ -493,6 +598,7 @@ class RenderTable extends RenderBox {
     markNeedsLayout();
   }
 
+  /// The style to use when painting the boundary and interior divisions of the table.
   TableBorder get border => _border;
   TableBorder _border;
   set border(TableBorder value) {
@@ -502,6 +608,11 @@ class RenderTable extends RenderBox {
     markNeedsPaint();
   }
 
+  /// The decorations to use for each row of the table.
+  ///
+  /// Row decorations fill the horizontal and vertical extent of each row in
+  /// the table, unlike decorations for individual cells, which might not fill
+  /// either.
   List<Decoration> get rowDecorations => new List<Decoration>.unmodifiable(_rowDecorations ?? const <Decoration>[]);
   List<Decoration> _rowDecorations;
   List<BoxPainter> _rowDecorationPainters;
@@ -534,6 +645,7 @@ class RenderTable extends RenderBox {
     }
   }
 
+  /// How cells that do not explicitly specify a vertical alignment are aligned vertically.
   TableCellVerticalAlignment get defaultVerticalAlignment => _defaultVerticalAlignment;
   TableCellVerticalAlignment _defaultVerticalAlignment;
   set defaultVerticalAlignment (TableCellVerticalAlignment value) {
@@ -543,6 +655,7 @@ class RenderTable extends RenderBox {
     markNeedsLayout();
   }
 
+  /// The text baseline to use when aligning rows using [TableCellVerticalAlignment.baseline].
   TextBaseline get textBaseline => _textBaseline;
   TextBaseline _textBaseline;
   set textBaseline (TextBaseline value) {
@@ -558,6 +671,14 @@ class RenderTable extends RenderBox {
       child.parentData = new TableCellParentData();
   }
 
+  /// Replaces the children of this table with the given cells.
+  ///
+  /// The cells are divided into the specified number of columns before
+  /// replacing the existing children.
+  ///
+  /// If the new cells contain any existing children of the table, those
+  /// children are simply moved to their new location in the table rather than
+  /// removed from the table and re-added.
   void setFlatChildren(int columns, List<RenderBox> cells) {
     if (cells == _children && columns == _columns)
       return;
@@ -617,6 +738,7 @@ class RenderTable extends RenderBox {
     markNeedsLayout();
   }
 
+  /// Replaces the children of this table with the given cells.
   void setChildren(List<List<RenderBox>> cells) {
     // TODO(ianh): Make this smarter, like setFlatChildren
     if (cells == null) {
@@ -635,6 +757,9 @@ class RenderTable extends RenderBox {
     assert(_children.length == rows * columns);
   }
 
+  /// Adds a row to the end of the table.
+  ///
+  /// The newly added children must not already have parents.
   void addRow(List<RenderBox> cells) {
     assert(cells.length == columns);
     assert(_children.length == rows * columns);
@@ -647,6 +772,11 @@ class RenderTable extends RenderBox {
     markNeedsLayout();
   }
 
+  /// Replaces the child at the given position with the given child.
+  ///
+  /// If the given child is already located at the given position, this function
+  /// does not modify the table. Otherwise, the given child must not already
+  /// have a parent.
   void setChild(int x, int y, RenderBox value) {
     assert(x != null);
     assert(y != null);

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

@@ -83,6 +83,12 @@ class ViewportDimensions {
 /// have a child model. See [RenderViewport] for a viewport with a single child
 /// and [RenderVirtualViewport] for a viewport with multiple children.
 class RenderViewportBase extends RenderBox {
+  /// Initializes fields for subclasses.
+  ///
+  /// The [paintOffset] and [mainAxis] arguments must not be null.
+  ///
+  /// This constructor uses positional arguments rather than named arguments to
+  /// work around limitations of mixins.
   RenderViewportBase(
     Offset paintOffset,
     Axis mainAxis,
@@ -149,6 +155,7 @@ class RenderViewportBase extends RenderBox {
     markNeedsSemanticsUpdate();
   }
 
+  /// The interior and exterior extent of the viewport.
   ViewportDimensions get dimensions => _dimensions;
   ViewportDimensions _dimensions = ViewportDimensions.zero;
   set dimensions(ViewportDimensions value) {
@@ -181,16 +188,23 @@ class RenderViewportBase extends RenderBox {
   }
 }
 
+/// Signature for notifications about [RenderViewport] dimensions changing.
 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 is controlled by the
+/// the viewport. The portion of the child that is visible can be controlled
-/// paint offset.
+/// with the [paintOffset].
+///
+/// See also:
+///
+///  * [RenderVirtualViewport] (which works with more than one child)
 class RenderViewport extends RenderViewportBase with RenderObjectWithChildMixin<RenderBox> {
-
+  /// Creates a render object that's bigger on the inside.
+  ///
+  /// The [paintOffset] and [mainAxis] arguments must not be null.
   RenderViewport({
     RenderBox child,
     Offset paintOffset: Offset.zero,
@@ -203,6 +217,9 @@ class RenderViewport extends RenderViewportBase with RenderObjectWithChildMixin<
 
   /// Called during [layout] to report the dimensions of the viewport
   /// and its child.
+  ///
+  /// The return value of this function is used as the new [paintOffset] and
+  /// must not be null.
   ViewportDimensionsChangeCallback onPaintOffsetUpdateNeeded;
 
   BoxConstraints _getInnerConstraints(BoxConstraints constraints) {
@@ -315,9 +332,24 @@ 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].
+///
+/// See also:
+///
+///  * [RenderList] (which arranges its children linearly)
+///  * [RenderGrid] (which arranges its children into tiles)
+///  * [RenderViewport] (which is easier to use with a single child)
 abstract class RenderVirtualViewport<T extends ContainerBoxParentDataMixin<RenderBox>>
     extends RenderViewportBase with ContainerRenderObjectMixin<RenderBox, T>,
                                     RenderBoxContainerDefaultsMixin<RenderBox, T> {
+  /// Initializes fields for subclasses.
+  ///
+  /// The [paintOffset] and [mainAxis] arguments must not be null.
   RenderVirtualViewport({
     int virtualChildCount,
     LayoutCallback callback,
@@ -328,6 +360,9 @@ abstract class RenderVirtualViewport<T extends ContainerBoxParentDataMixin<Rende
        _callback = callback,
        super(paintOffset, mainAxis, anchor);
 
+  /// The overall number of children this viewport could potentially display.
+  ///
+  /// If null, the viewport might display an unbounded number of children.
   int get virtualChildCount => _virtualChildCount;
   int _virtualChildCount;
   set virtualChildCount(int value) {

packages/flutter/lib/src/scheduler/binding.dart

@@ -343,6 +343,17 @@ abstract class SchedulerBinding extends BindingBase {
   bool get isProducingFrame => _isProducingFrame;
   bool _isProducingFrame = false;
 
+  /// Schedules a new frame using [scheduleFrame] if this object is not
+  /// currently producing a frame.
+  ///
+  /// After this is called, the framework ensures that the end of the
+  /// [handleBeginFrame] function will (eventually) be reached.
+  void ensureVisualUpdate() {
+    if (_isProducingFrame)
+      return;
+    scheduleFrame();
+  }
+
   /// If necessary, schedules a new frame by calling
   /// [ui.window.scheduleFrame].
   ///
@@ -350,12 +361,6 @@ abstract class SchedulerBinding extends BindingBase {
   /// [handleBeginFrame]. (This call might be delayed, e.g. if the
   /// device's screen is turned off it will typically be delayed until
   /// the screen is on and the application is visible.)
-  void ensureVisualUpdate() {
-    if (_isProducingFrame)
-      return;
-    scheduleFrame();
-  }
-
   void scheduleFrame() {
     if (_hasScheduledFrame)
       return;

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

@@ -1415,14 +1415,6 @@ class BlockBody extends MultiChildRenderObjectWidget {
   }
 }
 
-/// A base class for widgets that accept [Positioned] children.
-abstract class StackRenderObjectWidgetBase extends MultiChildRenderObjectWidget {
-  StackRenderObjectWidgetBase({
-    List<Widget> children: _emptyWidgetList,
-    Key key
-  }) : super(key: key, children: children);
-}
-
 /// Uses the stack layout algorithm for its children.
 ///
 /// This class is useful if you want to overlap several children in a
@@ -1446,7 +1438,11 @@ abstract class StackRenderObjectWidgetBase extends MultiChildRenderObjectWidget
 ///    the child according to a [FractionalOffset] value)
 ///  * [CustomSingleChildLayout]
 ///  * [CustomMultiChildLayout]
-class Stack extends StackRenderObjectWidgetBase {
+class Stack extends MultiChildRenderObjectWidget {
+  /// Creates a stack widget.
+  ///
+  /// By default, the non-positioned children of the stack are aligned by their
+  /// top left corners.
   Stack({
     Key key,
     List<Widget> children: _emptyWidgetList,
@@ -1454,6 +1450,11 @@ class Stack extends StackRenderObjectWidgetBase {
   }) : super(key: key, children: children);
 
   /// How to align the non-positioned children in the stack.
+  ///
+  /// The non-positioned children are placed relative to each other such that
+  /// the points determined by [alignment] are co-located. For example, if the
+  /// [alignment] is [FractionalOffset.topLeft], then the top left corner of
+  /// each non-positioned child will be located at the same global coordinate.
   final FractionalOffset alignment;
 
   @override
@@ -1466,22 +1467,22 @@ class Stack extends StackRenderObjectWidgetBase {
 }
 
 /// A [Stack] that shows a single child from a list of children.
-class IndexedStack extends StackRenderObjectWidgetBase {
+class IndexedStack extends Stack {
+  /// Creates a stack widget that paints a single child.
+  ///
+  /// The [index] argument must not be null.
   IndexedStack({
     Key key,
     List<Widget> children: _emptyWidgetList,
-    this.alignment: FractionalOffset.topLeft,
+    FractionalOffset alignment: FractionalOffset.topLeft,
     this.index: 0
-  }) : super(key: key, children: children) {
+  }) : super(key: key, alignment: alignment, children: children) {
     assert(index != null);
   }
 
   /// The index of the child to show.
   final int index;
 
-  /// How to align the non-positioned children in the stack.
-  final FractionalOffset alignment;
-
   @override
   RenderIndexedStack createRenderObject(BuildContext context) => new RenderIndexedStack(index: index, alignment: alignment);
 
@@ -1498,7 +1499,7 @@ class IndexedStack extends StackRenderObjectWidgetBase {
 /// 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).
-class Positioned extends ParentDataWidget<StackRenderObjectWidgetBase> {
+class Positioned extends ParentDataWidget<Stack> {
   /// Creates a Positioned object with the given values.
   ///
   /// Only two out of the three horizontal values ([left], [right],