Merge pull request #779 from abarth/basic_docs

Add some dartdoc to basic widgets

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

@@ -6,6 +6,7 @@ import 'box.dart';
 import 'object.dart';
 
 class MultiChildLayoutParentData extends ContainerBoxParentDataMixin<RenderBox> {
+  /// An object representing the identity of this child.
   Object id;
 
   void merge(MultiChildLayoutParentData other) {
@@ -17,6 +18,7 @@ class MultiChildLayoutParentData extends ContainerBoxParentDataMixin<RenderBox>
   String toString() => '${super.toString()}; id=$id';
 }
 
+/// A delegate that controls the layout of multiple children.
 abstract class MultiChildLayoutDelegate {
   Map<Object, RenderBox> _idToChild;
   Set<RenderBox> _debugChildrenNeedingLayout;
@@ -94,6 +96,12 @@ abstract class MultiChildLayoutDelegate {
   void performLayout(Size size, BoxConstraints constraints);
 }
 
+/// Defers the layout of multiple children to a delegate.
+///
+/// The delegate can determine the layout constraints for each child and can
+/// decide where to position each child. The delegate can also determine the
+/// size of the parent, but the size of the parent cannot depend on the sizes of
+/// the children.
 class RenderCustomMultiChildLayoutBox extends RenderBox
   with ContainerRenderObjectMixin<RenderBox, MultiChildLayoutParentData>,
        RenderBoxContainerDefaultsMixin<RenderBox, MultiChildLayoutParentData> {
@@ -110,6 +118,7 @@ class RenderCustomMultiChildLayoutBox extends RenderBox
       child.parentData = new MultiChildLayoutParentData();
   }
 
+  /// The delegate that controls the layout of the children.
   MultiChildLayoutDelegate get delegate => _delegate;
   MultiChildLayoutDelegate _delegate;
   void set delegate (MultiChildLayoutDelegate newDelegate) {

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

@@ -21,7 +21,7 @@ export 'package:flutter/gestures.dart' show
   PointerUpEvent,
   PointerCancelEvent;
 
-/// A base class for render objects that resemble their children
+/// A base class for render objects that resemble their children.
 ///
 /// A proxy box has a single child and simply mimics all the properties of that
 /// child by calling through to the child for each function in the render box
@@ -87,15 +87,16 @@ class RenderProxyBox extends RenderBox with RenderObjectWithChildMixin<RenderBox
   }
 }
 
-/// A render object that imposes additional constraints on its child
+/// Imposes additional constraints on its child.
 ///
 /// A render constrained box proxies most functions in the render box protocol
 /// to its child, except that when laying out its child, it tightens the
 /// constraints provided by its parent by enforcing the [additionalConstraints]
 /// as well.
 ///
-/// For example, if you wanted [child] to have a minimum height, you could use
-/// `const BoxConstraints(minHeight: 50.0)`` as the [additionalConstraints].
+/// For example, if you wanted [child] to have a minimum height of 50.0 logical
+/// pixels, you could use `const BoxConstraints(minHeight: 50.0)`` as the
+/// [additionalConstraints].
 class RenderConstrainedBox extends RenderProxyBox {
   RenderConstrainedBox({
     RenderBox child,
@@ -260,7 +261,7 @@ class RenderFractionallySizedBox extends RenderProxyBox {
   }
 }
 
-/// Forces child to layout at a specific aspect ratio
+/// Forces child to layout at a specific aspect ratio.
 ///
 /// The width of this render object is the largest width permited by the layout
 /// constraints. The height of the render object is determined by applying the
@@ -284,7 +285,7 @@ class RenderAspectRatio extends RenderProxyBox {
     assert(_aspectRatio != null);
   }
 
-  /// The aspect ratio to use when computing the height from the width
+  /// The aspect ratio to use when computing the height from the width.
   ///
   /// The aspect ratio is expressed as a ratio of width to height. For example,
   /// a 16:9 width:height aspect ratio would have a value of 16.0/9.0.
@@ -329,18 +330,18 @@ class RenderAspectRatio extends RenderProxyBox {
   }
 }
 
-/// Sizes its child to the child's intrinsic width
+/// Sizes its child to the child's intrinsic width.
 ///
-/// This class will size its child's width to the child's maximum intrinsic
-/// width. If [stepWidth] is non-null, the child's width will be snapped to a
-/// multiple of the [stepWidth]. Similarly, if [stepHeight] is non-null, the
-/// child's height will be snapped to a multiple of the [stepHeight].
+/// Sizes its child's width to the child's maximum intrinsic width. If
+/// [stepWidth] is non-null, the child's width will be snapped to a multiple of
+/// the [stepWidth]. Similarly, if [stepHeight] is non-null, the child's height
+/// will be snapped to a multiple of the [stepHeight].
 ///
 /// This class is useful, for example, when unlimited width is available and
 /// you would like a child that would otherwise attempt to expand infinitely to
 /// instead size itself to a more reasonable width.
 ///
-/// Note: This class is relatively expensive. Avoid using it where possible.
+/// This class is relatively expensive. Avoid using it where possible.
 class RenderIntrinsicWidth extends RenderProxyBox {
 
   RenderIntrinsicWidth({
@@ -349,7 +350,7 @@ class RenderIntrinsicWidth extends RenderProxyBox {
     RenderBox child
   }) : _stepWidth = stepWidth, _stepHeight = stepHeight, super(child);
 
-  /// If non-null, force the child's width to be a multiple of this value
+  /// If non-null, force the child's width to be a multiple of this value.
   double get stepWidth => _stepWidth;
   double _stepWidth;
   void set stepWidth(double newStepWidth) {
@@ -359,7 +360,7 @@ class RenderIntrinsicWidth extends RenderProxyBox {
     markNeedsLayout();
   }
 
-  /// If non-null, force the child's height to be a multiple of this value
+  /// If non-null, force the child's height to be a multiple of this value.
   double get stepHeight => _stepHeight;
   double _stepHeight;
   void set stepHeight(double newStepHeight) {
@@ -428,16 +429,13 @@ class RenderIntrinsicWidth extends RenderProxyBox {
   }
 }
 
-/// Sizes its child to the child's intrinsic height
-///
-/// This class will size its child's height to the child's maximum intrinsic
-/// height.
+/// Sizes its child to the child's intrinsic height.
 ///
 /// This class is useful, for example, when unlimited height is available and
 /// you would like a child that would otherwise attempt to expand infinitely to
 /// instead size itself to a more reasonable height.
 ///
-/// Note: This class is relatively expensive. Avoid using it where possible.
+/// This class is relatively expensive. Avoid using it where possible.
 class RenderIntrinsicHeight extends RenderProxyBox {
 
   RenderIntrinsicHeight({
@@ -486,20 +484,20 @@ class RenderIntrinsicHeight extends RenderProxyBox {
 
 }
 
-/// Makes its child partially transparent
+/// Makes its child partially transparent.
 ///
 /// This class paints its child into an intermediate buffer and then blends the
 /// child back into the scene partially transparent.
 ///
-/// Note: This class is relatively expensive because it requires painting the
-/// child into an intermediate buffer.
+/// This class is relatively expensive because it requires painting the child
+/// into an intermediate buffer.
 class RenderOpacity extends RenderProxyBox {
   RenderOpacity({ RenderBox child, double opacity })
     : this._opacity = opacity, super(child) {
     assert(opacity >= 0.0 && opacity <= 1.0);
   }
 
-  /// The fraction to scale the child's alpha value
+  /// The fraction to scale the child's alpha value.
   ///
   /// An opacity of 1.0 is fully opaque. An opacity of 0.0 is fully transparent
   /// (i.e., invisible).
@@ -566,7 +564,10 @@ class RenderShaderMask extends RenderProxyBox {
   }
 }
 
+/// A class that provides custom clips.
 abstract class CustomClipper<T> {
+  /// Returns a description of the clip given that the render object being
+  /// clipped is of the given size.
   T getClip(Size size);
   bool shouldRepaint(CustomClipper oldClipper);
 }
@@ -577,6 +578,7 @@ abstract class _RenderCustomClip<T> extends RenderProxyBox {
     CustomClipper<T> clipper
   }) : _clipper = clipper, super(child);
 
+  /// If non-null, determines which clip to use on the child.
   CustomClipper<T> get clipper => _clipper;
   CustomClipper<T> _clipper;
   void set clipper (CustomClipper<T> newClipper) {
@@ -598,7 +600,7 @@ abstract class _RenderCustomClip<T> extends RenderProxyBox {
   T get _clip => _clipper?.getClip(size) ?? _defaultClip;
 }
 
-/// Clips its child using a rectangle
+/// Clips its child using a rectangle.
 ///
 /// Prevents its child from painting outside its bounds.
 class RenderClipRect extends _RenderCustomClip<Rect> {
@@ -624,7 +626,7 @@ class RenderClipRect extends _RenderCustomClip<Rect> {
   }
 }
 
-/// Clips its child using a rounded rectangle
+/// Clips its child using a rounded rectangle.
 ///
 /// Creates a rounded rectangle from its layout dimensions and the given x and
 /// y radius values and prevents its child from painting outside that rounded
@@ -639,7 +641,7 @@ class RenderClipRRect extends RenderProxyBox {
     assert(_yRadius != null);
   }
 
-  /// The radius of the rounded corners in the horizontal direction in logical pixels
+  /// The radius of the rounded corners in the horizontal direction in logical pixels.
   ///
   /// Values are clamped to be between zero and half the width of the render
   /// object.
@@ -653,7 +655,7 @@ class RenderClipRRect extends RenderProxyBox {
     markNeedsPaint();
   }
 
-  /// The radius of the rounded corners in the vertical direction in logical pixels
+  /// The radius of the rounded corners in the vertical direction in logical pixels.
   ///
   /// Values are clamped to be between zero and half the height of the render
   /// object.
@@ -676,7 +678,7 @@ class RenderClipRRect extends RenderProxyBox {
   }
 }
 
-/// Clips its child using an oval
+/// Clips its child using an oval.
 ///
 /// Inscribes an oval into its layout dimensions and prevents its child from
 /// painting outside that oval.
@@ -717,16 +719,16 @@ class RenderClipOval extends _RenderCustomClip<Rect> {
   }
 }
 
-/// Where to paint a box decoration
+/// Where to paint a box decoration.
 enum BoxDecorationPosition {
-  /// Paint the box decoration behind the children
+  /// Paint the box decoration behind the children.
   background,
 
-  /// Paint the box decoration in front of the children
+  /// Paint the box decoration in front of the children.
   foreground,
 }
 
-/// Paints a [BoxDecoration] either before or after its child paints
+/// Paints a [BoxDecoration] either before or after its child paints.
 class RenderDecoratedBox extends RenderProxyBox {
 
   RenderDecoratedBox({
@@ -740,7 +742,7 @@ class RenderDecoratedBox extends RenderProxyBox {
     assert(position != null);
   }
 
-  /// Where to paint the box decoration
+  /// Where to paint the box decoration.
   BoxDecorationPosition get position => _position;
   BoxDecorationPosition _position;
   void set position (BoxDecorationPosition newPosition) {
@@ -750,7 +752,7 @@ class RenderDecoratedBox extends RenderProxyBox {
     markNeedsPaint();
   }
 
-  /// What decoration to paint
+  /// What decoration to paint.
   BoxDecoration get decoration => _painter.decoration;
   void set decoration (BoxDecoration newDecoration) {
     assert(newDecoration != null);
@@ -820,7 +822,7 @@ class RenderDecoratedBox extends RenderProxyBox {
   }
 }
 
-/// Applies a transformation before painting its child
+/// Applies a transformation before painting its child.
 class RenderTransform extends RenderProxyBox {
   RenderTransform({
     Matrix4 transform,
@@ -836,7 +838,7 @@ class RenderTransform extends RenderProxyBox {
   }
 
   /// The origin of the coordinate system (relative to the upper left corder of
-  /// this render object) in which to apply the matrix
+  /// this render object) in which to apply the matrix.
   ///
   /// Setting an origin is equivalent to conjugating the transform matrix by a
   /// translation. This property is provided just for convenience.
@@ -866,7 +868,7 @@ class RenderTransform extends RenderProxyBox {
   // Note the lack of a getter for transform because Matrix4 is not immutable
   Matrix4 _transform;
 
-  /// The matrix to transform the child by during painting
+  /// The matrix to transform the child by during painting.
   void set transform(Matrix4 newTransform) {
     assert(newTransform != null);
     if (_transform == newTransform)
@@ -875,37 +877,37 @@ class RenderTransform extends RenderProxyBox {
     markNeedsPaint();
   }
 
-  /// Sets the transform to the identity matrix
+  /// Sets the transform to the identity matrix.
   void setIdentity() {
     _transform.setIdentity();
     markNeedsPaint();
   }
 
-  /// Concatenates a rotation about the x axis into the transform
+  /// Concatenates a rotation about the x axis into the transform.
   void rotateX(double radians) {
     _transform.rotateX(radians);
     markNeedsPaint();
   }
 
-  /// Concatenates a rotation about the y axis into the transform
+  /// Concatenates a rotation about the y axis into the transform.
   void rotateY(double radians) {
     _transform.rotateY(radians);
     markNeedsPaint();
   }
 
-  /// Concatenates a rotation about the z axis into the transform
+  /// Concatenates a rotation about the z axis into the transform.
   void rotateZ(double radians) {
     _transform.rotateZ(radians);
     markNeedsPaint();
   }
 
-  /// Concatenates a translation by (x, y, z) into the transform
+  /// Concatenates a translation by (x, y, z) into the transform.
   void translate(x, [double y = 0.0, double z = 0.0]) {
     _transform.translate(x, y, z);
     markNeedsPaint();
   }
 
-  /// Concatenates a scale into the transform
+  /// Concatenates a scale into the transform.
   void scale(x, [double y, double z]) {
     _transform.scale(x, y, z);
     markNeedsPaint();
@@ -963,13 +965,13 @@ class RenderTransform extends RenderProxyBox {
   }
 }
 
-/// Called when a size changes
+/// Called when a size changes.
 typedef void SizeChangedCallback(Size newSize);
 
 /// Calls [onSizeChanged] whenever the child's layout size changes
 ///
-/// Note: Size observer calls its callback during layout, which means you cannot
-/// dirty layout information during the callback.
+/// Because size observer calls its callback during layout, you cannot modify
+/// layout information during the callback.
 class RenderSizeObserver extends RenderProxyBox {
   RenderSizeObserver({
     this.onSizeChanged,
@@ -1007,13 +1009,13 @@ abstract class CustomPainter {
 /// current canvas and then paints its children. After painting its children,
 /// custom paint asks foregroundPainter to paint. The coodinate system of the
 /// canvas matches the coordinate system of the custom paint object. The
-/// painters are expected to paint with in a rectangle starting at the origin
+/// painters are expected to paint within a rectangle starting at the origin
 /// and encompassing a region of the given size. If the painters paints outside
 /// those bounds, there might be insufficient memory allocated to rasterize the
 /// painting commands and the resulting behavior is undefined.
 ///
-/// Note: Custom paint calls its painters during paint, which means you cannot
-/// dirty layout or paint information during the callback.
+/// Because custom paint calls its painters during paint, you cannot dirty
+/// layout or paint information during the callback.
 class RenderCustomPaint extends RenderProxyBox {
   RenderCustomPaint({
     CustomPainter painter,

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

@@ -72,15 +72,24 @@ abstract class RenderShiftedBox extends RenderBox with RenderObjectWithChildMixi
 
 }
 
+/// Insets its child by the given padding.
+///
+/// When passing layout constraints to its child, padding shrinks the
+/// constraints by the given padding, causing the child to layout at a smaller
+/// size. Padding then sizes itself to its child's size, inflated by the
+/// padding, effectively creating empty space around the child.
 class RenderPadding extends RenderShiftedBox {
-
-  RenderPadding({ EdgeDims padding, RenderBox child }) : super(child) {
+  RenderPadding({
+    EdgeDims padding,
+    RenderBox child
+  }) : _padding = padding, super(child) {
     assert(padding != null);
-    this.padding = padding;
+    assert(padding.isNonNegative);
   }
 
-  EdgeDims _padding;
+  /// The amount to pad the child in each dimension.
   EdgeDims get padding => _padding;
+  EdgeDims _padding;
   void set padding (EdgeDims value) {
     assert(value != null);
     assert(value.isNonNegative);
@@ -143,14 +152,12 @@ class RenderPadding extends RenderShiftedBox {
   }
 }
 
+/// Aligns its child box within itself.
+///
+/// For example, to align a box at the bottom right, you would pass this box a
+/// tight constraint that is bigger than the child's natural size,
+/// with horizontal and vertical set to 1.0.
 class RenderPositionedBox extends RenderShiftedBox {
-
-  // This box aligns a child box within itself. It's only useful for
-  // children that don't always size to fit their parent. For example,
-  // to align a box at the bottom right, you would pass this box a
-  // tight constraint that is bigger than the child's natural size,
-  // with horizontal and vertical set to 1.0.
-
   RenderPositionedBox({
     RenderBox child,
     FractionalOffset alignment: const FractionalOffset(0.5, 0.5),
@@ -160,9 +167,20 @@ class RenderPositionedBox extends RenderShiftedBox {
        _widthFactor = widthFactor,
        _heightFactor = heightFactor,
        super(child) {
-    assert(alignment != null);
-  }
-
+    assert(alignment != null && alignment.x != null && alignment.y != null);
+    assert(widthFactor == null || widthFactor >= 0.0);
+    assert(heightFactor == null || heightFactor >= 0.0);
+  }
+
+  /// How to align the child.
+  ///
+  /// The x and y values of the alignment control the horizontal and vertical
+  /// alignment, respectively.  An x value of 0.0 means that the left edge of
+  /// the child is aligned with the left edge of the parent whereas an x value
+  /// of 1.0 means that the right edge of the child is aligned with the right
+  /// edge of the parent. Other values interpolate (and extrapolate) linearly.
+  /// For example, a value of 0.5 means that the center of the child is aligned
+  /// with the center of the parent.
   FractionalOffset get alignment => _alignment;
   FractionalOffset _alignment;
   void set alignment (FractionalOffset newAlignment) {
@@ -173,18 +191,26 @@ class RenderPositionedBox extends RenderShiftedBox {
     markNeedsLayout();
   }
 
-  double _widthFactor;
+  /// If non-null, sets its width to the child's width multipled by this factor.
+  ///
+  /// Can be both greater and less than 1.0 but must be positive.
   double get widthFactor => _widthFactor;
+  double _widthFactor;
   void set widthFactor (double value) {
+    assert(value == null || value >= 0.0);
     if (_widthFactor == value)
       return;
     _widthFactor = value;
     markNeedsLayout();
   }
 
-  double _heightFactor;
+  /// If non-null, sets its height to the child's height multipled by this factor.
+  ///
+  /// Can be both greater and less than 1.0 but must be positive.
   double get heightFactor => _heightFactor;
+  double _heightFactor;
   void set heightFactor (double value) {
+    assert(value == null || value >= 0.0);
     if (_heightFactor == value)
       return;
     _heightFactor = value;
@@ -226,6 +252,12 @@ class OneChildLayoutDelegate {
   Point getPositionForChild(Size size, Size childSize) => Point.origin;
 }
 
+/// Defers the layout of its single child to a delegate.
+///
+/// The delegate can determine the layout constraints for the child and can
+/// decide where to position the child. The delegate can also determine the size
+/// of the parent, but the size of the parent cannot depend on the size of the
+/// child.
 class RenderCustomOneChildLayoutBox extends RenderShiftedBox {
   RenderCustomOneChildLayoutBox({
     RenderBox child,
@@ -234,6 +266,7 @@ class RenderCustomOneChildLayoutBox extends RenderShiftedBox {
     assert(delegate != null);
   }
 
+  /// A delegate that controls this object's layout.
   OneChildLayoutDelegate get delegate => _delegate;
   OneChildLayoutDelegate _delegate;
   void set delegate (OneChildLayoutDelegate newDelegate) {

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

@@ -21,13 +21,15 @@ enum ScrollDirection {
   both
 }
 
-/// A render object that's bigger on the inside
+/// A render object that's bigger on the inside.
 ///
-/// A viewport is the core scrolling primitive in the render tree. 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 portiion of the child that is visible is controlled by the scroll
-/// offset.
+/// 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
+/// scroll offset.
+///
+/// Viewport is the core scrolling primitive in the system, but it can be used
+/// in other situations.
 class RenderViewport extends RenderBox with RenderObjectWithChildMixin<RenderBox> {
 
   RenderViewport({
@@ -51,7 +53,7 @@ class RenderViewport extends RenderBox with RenderObjectWithChildMixin<RenderBox
     }
   }
 
-  /// The offset at which to paint the child
+  /// The offset at which to paint the child.
   ///
   /// The offset can be non-zero only in the [scrollDirection].
   Offset get scrollOffset => _scrollOffset;
@@ -64,7 +66,7 @@ class RenderViewport extends RenderBox with RenderObjectWithChildMixin<RenderBox
     markNeedsPaint();
   }
 
-  /// In which direction the child is permitted to be larger than the viewport
+  /// The direction in which the child is permitted to be larger than the viewport
   ///
   /// If the viewport is scrollable in a particular direction (e.g., vertically),
   /// the child is given layout constraints that are fully unconstrainted in

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

@@ -72,12 +72,23 @@ export 'package:flutter/rendering.dart' show
 
 // PAINTING NODES
 
+/// Makes its child partially transparent.
+///
+/// This class paints its child into an intermediate buffer and then blends the
+/// child back into the scene partially transparent.
+///
+/// This class is relatively expensive because it requires painting the child
+/// into an intermediate buffer.
 class Opacity extends OneChildRenderObjectWidget {
   Opacity({ Key key, this.opacity, Widget child })
     : super(key: key, child: child) {
     assert(opacity >= 0.0 && opacity <= 1.0);
   }
 
+  /// The fraction to scale the child's alpha value.
+  ///
+  /// An opacity of 1.0 is fully opaque. An opacity of 0.0 is fully transparent
+  /// (i.e., invisible).
   final double opacity;
 
   RenderOpacity createRenderObject() => new RenderOpacity(opacity: opacity);
@@ -119,6 +130,7 @@ class ShaderMask extends OneChildRenderObjectWidget {
   }
 }
 
+/// Paints a [BoxDecoration] either before or after its child paints.
 class DecoratedBox extends OneChildRenderObjectWidget {
   DecoratedBox({
     Key key,
@@ -130,10 +142,13 @@ class DecoratedBox extends OneChildRenderObjectWidget {
     assert(position != null);
   }
 
+  /// What decoration to paint.
   final BoxDecoration decoration;
+
+  /// Where to paint the box decoration.
   final BoxDecorationPosition position;
 
-  RenderObject createRenderObject() => new RenderDecoratedBox(decoration: decoration, position: position);
+  RenderDecoratedBox createRenderObject() => new RenderDecoratedBox(decoration: decoration, position: position);
 
   void updateRenderObject(RenderDecoratedBox renderObject, DecoratedBox oldWidget) {
     renderObject.decoration = decoration;
@@ -141,11 +156,27 @@ class DecoratedBox extends OneChildRenderObjectWidget {
   }
 }
 
+/// Delegates its painting.
+///
+/// When asked to paint, custom paint first asks painter to paint with the
+/// current canvas and then paints its children. After painting its children,
+/// custom paint asks foregroundPainter to paint. The coodinate system of the
+/// canvas matches the coordinate system of the custom paint object. The
+/// painters are expected to paint within a rectangle starting at the origin
+/// and encompassing a region of the given size. If the painters paints outside
+/// those bounds, there might be insufficient memory allocated to rasterize the
+/// painting commands and the resulting behavior is undefined.
+///
+/// Because custom paint calls its painters during paint, you cannot dirty
+/// layout or paint information during the callback.
 class CustomPaint extends OneChildRenderObjectWidget {
   CustomPaint({ Key key, this.painter, this.foregroundPainter, Widget child })
     : super(key: key, child: child);
 
+  /// The painter that paints before the children.
   final CustomPainter painter;
+
+  /// The painter that paints after the children.
   final CustomPainter foregroundPainter;
 
   RenderCustomPaint createRenderObject() => new RenderCustomPaint(
@@ -164,9 +195,13 @@ class CustomPaint extends OneChildRenderObjectWidget {
   }
 }
 
+/// Clips its child using a rectangle.
+///
+/// Prevents its child from painting outside its bounds.
 class ClipRect extends OneChildRenderObjectWidget {
   ClipRect({ Key key, this.clipper, Widget child }) : super(key: key, child: child);
 
+  /// If non-null, determines which clip to use.
   final CustomClipper<Rect> clipper;
 
   RenderClipRect createRenderObject() => new RenderClipRect(clipper: clipper);
@@ -180,11 +215,25 @@ class ClipRect extends OneChildRenderObjectWidget {
   }
 }
 
+/// Clips its child using a rounded rectangle.
+///
+/// Creates a rounded rectangle from its layout dimensions and the given x and
+/// y radius values and prevents its child from painting outside that rounded
+/// rectangle.
 class ClipRRect extends OneChildRenderObjectWidget {
   ClipRRect({ Key key, this.xRadius, this.yRadius, Widget child })
     : super(key: key, child: child);
 
+  /// The radius of the rounded corners in the horizontal direction in logical pixels.
+  ///
+  /// Values are clamped to be between zero and half the width of the render
+  /// object.
   final double xRadius;
+
+  /// The radius of the rounded corners in the vertical direction in logical pixels.
+  ///
+  /// Values are clamped to be between zero and half the height of the render
+  /// object.
   final double yRadius;
 
   RenderClipRRect createRenderObject() => new RenderClipRRect(xRadius: xRadius, yRadius: yRadius);
@@ -195,9 +244,14 @@ class ClipRRect extends OneChildRenderObjectWidget {
   }
 }
 
+/// Clips its child using an oval.
+///
+/// Inscribes an oval into its layout dimensions and prevents its child from
+/// painting outside that oval.
 class ClipOval extends OneChildRenderObjectWidget {
   ClipOval({ Key key, this.clipper, Widget child }) : super(key: key, child: child);
 
+  /// If non-null, determines which clip to use.
   final CustomClipper<Rect> clipper;
 
   RenderClipOval createRenderObject() => new RenderClipOval(clipper: clipper);
@@ -214,14 +268,27 @@ class ClipOval extends OneChildRenderObjectWidget {
 
 // POSITIONING AND SIZING NODES
 
+/// Applies a transformation before painting its child.
 class Transform extends OneChildRenderObjectWidget {
   Transform({ Key key, this.transform, this.origin, this.alignment, Widget child })
     : super(key: key, child: child) {
     assert(transform != null);
   }
 
+  /// The matrix to transform the child by during painting.
   final Matrix4 transform;
+
+  /// The origin of the coordinate system (relative to the upper left corder of
+  /// this render object) in which to apply the matrix.
+  ///
+  /// Setting an origin is equivalent to conjugating the transform matrix by a
+  /// translation. This property is provided just for convenience.
   final Offset origin;
+
+  /// The alignment of the origin, relative to the size of the box.
+  ///
+  /// This is equivalent to setting an origin based on the size of the box.
+  /// If it is specificed at the same time as an offset, both are applied.
   final FractionalOffset alignment;
 
   RenderTransform createRenderObject() => new RenderTransform(transform: transform, origin: origin, alignment: alignment);
@@ -233,12 +300,19 @@ class Transform extends OneChildRenderObjectWidget {
   }
 }
 
+/// Insets its child by the given padding.
+///
+/// When passing layout constraints to its child, padding shrinks the
+/// constraints by the given padding, causing the child to layout at a smaller
+/// size. Padding then sizes itself to its child's size, inflated by the
+/// padding, effectively creating empty space around the child.
 class Padding extends OneChildRenderObjectWidget {
   Padding({ Key key, this.padding, Widget child })
     : super(key: key, child: child) {
     assert(padding != null);
   }
 
+  /// The amount to pad the child in each dimension.
   final EdgeDims padding;
 
   RenderPadding createRenderObject() => new RenderPadding(padding: padding);
@@ -248,6 +322,11 @@ class Padding extends OneChildRenderObjectWidget {
   }
 }
 
+/// Aligns its child box within itself.
+///
+/// For example, to align a box at the bottom right, you would pass this box a
+/// tight constraint that is bigger than the child's natural size,
+/// with horizontal and vertical set to 1.0.
 class Align extends OneChildRenderObjectWidget {
   Align({
     Key key,
@@ -255,10 +334,31 @@ class Align extends OneChildRenderObjectWidget {
     this.widthFactor,
     this.heightFactor,
     Widget child
-  }) : super(key: key, child: child);
+  }) : super(key: key, child: child) {
+    assert(alignment != null && alignment.x != null && alignment.y != null);
+    assert(widthFactor == null || widthFactor >= 0.0);
+    assert(heightFactor == null || heightFactor >= 0.0);
+  }
 
+  /// How to align the child.
+  ///
+  /// The x and y values of the alignment control the horizontal and vertical
+  /// alignment, respectively.  An x value of 0.0 means that the left edge of
+  /// the child is aligned with the left edge of the parent whereas an x value
+  /// of 1.0 means that the right edge of the child is aligned with the right
+  /// edge of the parent. Other values interpolate (and extrapolate) linearly.
+  /// For example, a value of 0.5 means that the center of the child is aligned
+  /// with the center of the parent.
   final FractionalOffset alignment;
+
+  /// If non-null, sets its width to the child's width multipled by this factor.
+  ///
+  /// Can be both greater and less than 1.0 but must be positive.
   final double widthFactor;
+
+  /// If non-null, sets its height to the child's height multipled by this factor.
+  ///
+  /// Can be both greater and less than 1.0 but must be positive.
   final double heightFactor;
 
   RenderPositionedBox createRenderObject() => new RenderPositionedBox(alignment: alignment, widthFactor: widthFactor, heightFactor: heightFactor);
@@ -270,11 +370,18 @@ class Align extends OneChildRenderObjectWidget {
   }
 }
 
+/// Centers its child within itself.
 class Center extends Align {
   Center({ Key key, widthFactor, heightFactor, Widget child })
     : super(key: key, widthFactor: widthFactor, heightFactor: heightFactor, child: child);
 }
 
+/// Defers the layout of its single child to a delegate.
+///
+/// The delegate can determine the layout constraints for the child and can
+/// decide where to position the child. The delegate can also determine the size
+/// of the parent, but the size of the parent cannot depend on the size of the
+/// child.
 class CustomOneChildLayout extends OneChildRenderObjectWidget {
   CustomOneChildLayout({
     Key key,
@@ -304,6 +411,7 @@ class CustomOneChildLayout extends OneChildRenderObjectWidget {
   }
 }
 
+/// Metadata for identifying children in a [CustomMultiChildLayout].
 class LayoutId extends ParentDataWidget {
   LayoutId({
     Key key,
@@ -314,6 +422,7 @@ class LayoutId extends ParentDataWidget {
     assert(id != null);
   }
 
+  /// An object representing the identity of this child.
   final Object id;
 
   void debugValidateAncestor(Widget ancestor) {
@@ -340,6 +449,12 @@ class LayoutId extends ParentDataWidget {
   }
 }
 
+/// Defers the layout of multiple children to a delegate.
+///
+/// The delegate can determine the layout constraints for each child and can
+/// decide where to position each child. The delegate can also determine the
+/// size of the parent, but the size of the parent cannot depend on the sizes of
+/// the children.
 class CustomMultiChildLayout extends MultiChildRenderObjectWidget {
   CustomMultiChildLayout(List<Widget> children, {
     Key key,
@@ -349,6 +464,7 @@ class CustomMultiChildLayout extends MultiChildRenderObjectWidget {
     assert(delegate != null);
   }
 
+  /// The delegate that controls the layout of the children.
   final MultiChildLayoutDelegate delegate;
   final Object token;
 
@@ -363,11 +479,18 @@ class CustomMultiChildLayout extends MultiChildRenderObjectWidget {
   }
 }
 
+/// A box with a specified size.
+///
+/// Forces its child to have a specific width and/or height and sizes itself to
+/// match the size of its child.
 class SizedBox extends OneChildRenderObjectWidget {
   SizedBox({ Key key, this.width, this.height, Widget child })
     : super(key: key, child: child);
 
+  /// If non-null, requires the child to have exactly this width.
   final double width;
+
+  /// If non-null, requires the child to have exactly this height.
   final double height;
 
   RenderConstrainedBox createRenderObject() => new RenderConstrainedBox(
@@ -396,12 +519,18 @@ class SizedBox extends OneChildRenderObjectWidget {
   }
 }
 
+/// Imposes additional constraints on its child.
+///
+/// For example, if you wanted [child] to have a minimum height of 50.0 logical
+/// pixels, you could use `const BoxConstraints(minHeight: 50.0)`` as the
+/// [additionalConstraints].
 class ConstrainedBox extends OneChildRenderObjectWidget {
   ConstrainedBox({ Key key, this.constraints, Widget child })
     : super(key: key, child: child) {
     assert(constraints != null);
   }
 
+  /// The additional constraints to impose on the child.
   final BoxConstraints constraints;
 
   RenderConstrainedBox createRenderObject() => new RenderConstrainedBox(additionalConstraints: constraints);
@@ -479,6 +608,9 @@ class SizedOverflowBox extends OneChildRenderObjectWidget {
   }
 }
 
+/// Lays the child out as if it was in the tree, but without painting anything,
+/// without making the child available for hit testing, and without taking any
+/// room in the parent.
 class OffStage extends OneChildRenderObjectWidget {
   OffStage({ Key key, Widget child })
     : super(key: key, child: child);
@@ -506,11 +638,26 @@ class AspectRatio extends OneChildRenderObjectWidget {
   }
 }
 
+/// Sizes its child to the child's intrinsic width.
+///
+/// Sizes its child's width to the child's maximum intrinsic width. If
+/// [stepWidth] is non-null, the child's width will be snapped to a multiple of
+/// the [stepWidth]. Similarly, if [stepHeight] is non-null, the child's height
+/// will be snapped to a multiple of the [stepHeight].
+///
+/// This class is useful, for example, when unlimited width is available and
+/// you would like a child that would otherwise attempt to expand infinitely to
+/// instead size itself to a more reasonable width.
+///
+/// This class is relatively expensive. Avoid using it where possible.
 class IntrinsicWidth extends OneChildRenderObjectWidget {
   IntrinsicWidth({ Key key, this.stepWidth, this.stepHeight, Widget child })
     : super(key: key, child: child);
 
+  /// If non-null, force the child's width to be a multiple of this value.
   final double stepWidth;
+
+  /// If non-null, force the child's height to be a multiple of this value.
   final double stepHeight;
 
   RenderIntrinsicWidth createRenderObject() => new RenderIntrinsicWidth(stepWidth: stepWidth, stepHeight: stepHeight);
@@ -521,6 +668,13 @@ class IntrinsicWidth extends OneChildRenderObjectWidget {
   }
 }
 
+/// Sizes its child to the child's intrinsic height.
+///
+/// This class is useful, for example, when unlimited height is available and
+/// you would like a child that would otherwise attempt to expand infinitely to
+/// instead size itself to a more reasonable height.
+///
+/// This class is relatively expensive. Avoid using it where possible.
 class IntrinsicHeight extends OneChildRenderObjectWidget {
   IntrinsicHeight({ Key key, Widget child }) : super(key: key, child: child);
   RenderIntrinsicHeight createRenderObject() => new RenderIntrinsicHeight();
@@ -544,6 +698,15 @@ class Baseline extends OneChildRenderObjectWidget {
   }
 }
 
+/// A widget 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
+/// scroll offset.
+///
+/// Viewport is the core scrolling primitive in the system, but it can be used
+/// in other situations.
 class Viewport extends OneChildRenderObjectWidget {
   Viewport({
     Key key,
@@ -555,7 +718,16 @@ class Viewport extends OneChildRenderObjectWidget {
     assert(scrollOffset != null);
   }
 
+  /// The direction in which the child is permitted to be larger than the viewport
+  ///
+  /// If the viewport is scrollable in a particular direction (e.g., vertically),
+  /// the child is given layout constraints that are fully unconstrainted in
+  /// that direction (e.g., the child can be as tall as it wants).
   final ScrollDirection scrollDirection;
+
+  /// The offset at which to paint the child.
+  ///
+  /// The offset can be non-zero only in the [scrollDirection].
   final Offset scrollOffset;
 
   RenderViewport createRenderObject() => new RenderViewport(scrollDirection: scrollDirection, scrollOffset: scrollOffset);
@@ -567,12 +739,17 @@ class Viewport extends OneChildRenderObjectWidget {
   }
 }
 
+/// Calls [onSizeChanged] whenever the child's layout size changes
+///
+/// Because size observer calls its callback during layout, you cannot modify
+/// layout information during the callback.
 class SizeObserver extends OneChildRenderObjectWidget {
   SizeObserver({ Key key, this.onSizeChanged, Widget child })
     : super(key: key, child: child) {
     assert(onSizeChanged != null);
   }
 
+  /// The callback to call whenever the child's layout size changes
   final SizeChangedCallback onSizeChanged;
 
   RenderSizeObserver createRenderObject() => new RenderSizeObserver(onSizeChanged: onSizeChanged);