Add some dartdoc to basic widgets

These docs are largely duplicated from the cooresponding rendering classes. I'm
not sure how we can avoid repeating ourselves.

Author: abarth

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,