Add dartdoc to RenderBlock and RenderFlex

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

@@ -12,9 +12,6 @@ import 'package:vector_math/vector_math.dart';
 
 export 'package:sky/painting.dart' show TextBaseline;
 
-// GENERIC BOX RENDERING
-// Anything that has a concept of x, y, width, height is going to derive from this
-
 // This class should only be used in debug builds
 class _DebugSize extends Size {
   _DebugSize(Size source, this._owner, this._canBeUsedByParent): super.copy(source);

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

@@ -9,7 +9,14 @@ import 'package:sky/src/rendering/object.dart';
 
 export 'package:sky/src/rendering/object.dart' show EventDisposition;
 
+/// Parent data for use with [RenderFlex]
 class FlexParentData extends BoxParentData with ContainerParentDataMixin<RenderBox> {
+  /// The flex factor to use for this child
+  ///
+  /// If null, the child is inflexible and determines its own size. If non-null,
+  /// the child is flexible and its extent in the main axis is determined by
+  /// dividing the free space (after placing the inflexible children)
+  /// according to the flex factors of the flexible children.
   int flex;
 
   void merge(FlexParentData other) {
@@ -21,29 +28,61 @@ class FlexParentData extends BoxParentData with ContainerParentDataMixin<RenderB
   String toString() => '${super.toString()}; flex=$flex';
 }
 
-enum FlexDirection { horizontal, vertical }
+/// The direction in which the box should flex
+enum FlexDirection {
+  /// Children are arranged horizontally, from left to right
+  horizontal,
+  /// Children are arranged vertically, from top to bottom
+  vertical
+}
 
+/// How the children should be placed along the main axis in a flex layout
 enum FlexJustifyContent {
+  /// Place the children as close to the start of the main axis as possible
   start,
+  /// Place the children as close to the end of the main axis as possible
   end,
+  /// Place the children as close to the middle of the main axis as possible
   center,
+  /// Place the free space evenly between the children
   spaceBetween,
+  /// Place the free space evenly between the children as well as before and after the first and last child
   spaceAround,
 }
 
+/// How the children should be placed along the cross axis in a flex layout
 enum FlexAlignItems {
+  /// Place the children as close to the start of the cross axis as possible
   start,
+  /// Place the children as close to the end of the cross axis as possible
   end,
+  /// Place the children as close to the middle of the cross axis as possible
   center,
+  /// Require the children to fill the cross axis
   stretch,
+  /// Place the children along the cross axis such that their baselines match
   baseline,
 }
 
 typedef double _ChildSizingFunction(RenderBox child, BoxConstraints constraints);
 
+/// Implements the flex layout algorithm
+///
+/// In flex layout, children are arranged linearly along the main axis (either
+/// horizontally or vertically). First, inflexible children (those with a null
+/// flex factor) are allocated space along the main axis. If the flex is given
+/// unlimited space in the main axis, the flex sizes its main axis to the total
+/// size of the inflexible children along the main axis and forbids flexible
+/// children. Otherwise, the flex expands to the maximum max-axis size and the
+/// remaining space along is divided among the flexible children according to
+/// their flex factors. Any remaining free space (i.e., if there aren't any
+/// flexible children) is allocated according to the [justifyContent] property.
+///
+/// In the cross axis, children determine their own size. The flex then sizes
+/// its cross axis to fix the largest of its children. The children are then
+/// positioned along the cross axis according to the [alignItems] property.
 class RenderFlex extends RenderBox with ContainerRenderObjectMixin<RenderBox, FlexParentData>,
                                         RenderBoxContainerDefaultsMixin<RenderBox, FlexParentData> {
-  // lays out RenderBox children using flexible layout
 
   RenderFlex({
     List<RenderBox> children,
@@ -58,8 +97,9 @@ class RenderFlex extends RenderBox with ContainerRenderObjectMixin<RenderBox, Fl
     addAll(children);
   }
 
-  FlexDirection _direction;
+  /// The direction to use as the main axis
   FlexDirection get direction => _direction;
+  FlexDirection _direction;
   void set direction (FlexDirection value) {
     if (_direction != value) {
       _direction = value;
@@ -67,8 +107,9 @@ class RenderFlex extends RenderBox with ContainerRenderObjectMixin<RenderBox, Fl
     }
   }
 
-  FlexJustifyContent _justifyContent;
+  /// How the children should be placed along the main axis
   FlexJustifyContent get justifyContent => _justifyContent;
+  FlexJustifyContent _justifyContent;
   void set justifyContent (FlexJustifyContent value) {
     if (_justifyContent != value) {
       _justifyContent = value;
@@ -76,8 +117,9 @@ class RenderFlex extends RenderBox with ContainerRenderObjectMixin<RenderBox, Fl
     }
   }
 
-  FlexAlignItems _alignItems;
+  /// How the children should be placed along the cross axis
   FlexAlignItems get alignItems => _alignItems;
+  FlexAlignItems _alignItems;
   void set alignItems (FlexAlignItems value) {
     if (_alignItems != value) {
       _alignItems = value;
@@ -85,8 +127,9 @@ class RenderFlex extends RenderBox with ContainerRenderObjectMixin<RenderBox, Fl
     }
   }
 
-  TextBaseline _textBaseline;
+  /// If using aligning items according to their baseline, which baseline to use
   TextBaseline get textBaseline => _textBaseline;
+  TextBaseline _textBaseline;
   void set textBaseline (TextBaseline value) {
     if (_textBaseline != value) {
       _textBaseline = value;
@@ -94,7 +137,7 @@ class RenderFlex extends RenderBox with ContainerRenderObjectMixin<RenderBox, Fl
     }
   }
 
-  // Set during layout if overflow occurred on the main axis
+  /// Set during layout if overflow occurred on the main axis
   double _overflow;
 
   void setupParentData(RenderBox child) {

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

@@ -8,6 +8,10 @@ import 'package:sky/painting.dart';
 import 'package:sky/src/rendering/object.dart';
 import 'package:sky/src/rendering/box.dart';
 
+/// An image in the render tree
+///
+/// The render image attempts to find a size for itself that fits in the given
+/// constraints and preserves the image's intrinisc aspect ratio.
 class RenderImage extends RenderBox {
   RenderImage({
     sky.Image image,
@@ -24,6 +28,7 @@ class RenderImage extends RenderBox {
       _repeat = repeat;
 
   sky.Image _image;
+  /// The image to display
   sky.Image get image => _image;
   void set image (sky.Image value) {
     if (value == _image)
@@ -35,6 +40,7 @@ class RenderImage extends RenderBox {
   }
 
   double _width;
+  /// If non-null, requires the image to have this width
   double get width => _width;
   void set width (double value) {
     if (value == _width)
@@ -44,6 +50,7 @@ class RenderImage extends RenderBox {
   }
 
   double _height;
+  /// If non-null, requires the image to have this height
   double get height => _height;
   void set height (double value) {
     if (value == _height)
@@ -53,6 +60,7 @@ class RenderImage extends RenderBox {
   }
 
   sky.ColorFilter _colorFilter;
+  /// If non-null, apply this color filter to the image before painint.
   sky.ColorFilter get colorFilter => _colorFilter;
   void set colorFilter (sky.ColorFilter value) {
     if (value == _colorFilter)
@@ -62,6 +70,7 @@ class RenderImage extends RenderBox {
   }
 
   ImageFit _fit;
+  /// How to inscribe the image into the place allocated during layout
   ImageFit get fit => _fit;
   void set fit (ImageFit value) {
     if (value == _fit)
@@ -71,6 +80,7 @@ class RenderImage extends RenderBox {
   }
 
   ImageRepeat _repeat;
+  /// Not yet implemented
   ImageRepeat get repeat => _repeat;
   void set repeat (ImageRepeat value) {
     if (value == _repeat)
@@ -79,6 +89,13 @@ class RenderImage extends RenderBox {
     markNeedsPaint();
   }
 
+  /// Find a size for the render image within the given constraints
+  ///
+  ///  - The dimensions of the RenderImage must fit within the constraints.
+  ///  - The aspect ratio of the RenderImage matches the instrinsic aspect
+  ///    ratio of the image.
+  ///  - The RenderImage's dimension are maximal subject to being smaller than
+  ///    the intrinsic size of the image.
   Size _sizeForConstraints(BoxConstraints constraints) {
     // Folds the given |width| and |height| into |cosntraints| so they can all
     // be treated uniformly.
@@ -90,16 +107,6 @@ class RenderImage extends RenderBox {
     if (constraints.isTight || _image == null)
       return constraints.smallest;
 
-    // This algorithm attempts to find a size for the RenderImage that fits in
-    // the given constraints and preserves the image's intrinisc aspect ratio.
-    // Its goals as follow:
-    //
-    //  - The dimensions of the RenderImage fit within the constraints.
-    //  - The aspect ratio of the RenderImage matches the instrinsic aspect
-    //    ratio of the image.
-    //  - The RenderImage's dimension are maximal subject to being smaller than
-    //    the intrinsic size of the image.
-
     double width = _image.width.toDouble();
     double height = _image.height.toDouble();
     assert(width > 0.0);

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

@@ -366,7 +366,7 @@ abstract class Constraints {
 
 typedef void RenderObjectVisitor(RenderObject child);
 typedef void LayoutCallback(Constraints constraints);
-typedef double DimensionCallback(Constraints constraints);
+typedef double ExtentCallback(Constraints constraints);
 
 /// An object in the render tree
 ///

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

@@ -43,16 +43,16 @@ class HomogeneousViewport extends RenderObjectWrapper {
     RenderBlockViewport result = new RenderBlockViewport();
     result.callback = layout;
     result.totalExtentCallback = getTotalExtent;
-    result.minCrossAxisDimensionCallback = getMinCrossAxisDimension;
-    result.maxCrossAxisDimensionCallback = getMaxCrossAxisDimension;
+    result.minCrossAxisExtentCallback = getMinCrossAxisExtent;
+    result.maxCrossAxisExtentCallback = getMaxCrossAxisExtent;
     return result;
   }
 
   void remove() {
     renderObject.callback = null;
     renderObject.totalExtentCallback = null;
-    renderObject.minCrossAxisDimensionCallback = null;
-    renderObject.maxCrossAxisDimensionCallback = null;
+    renderObject.minCrossAxisExtentCallback = null;
+    renderObject.maxCrossAxisExtentCallback = null;
     super.remove();
     _children.clear();
     _layoutDirty = true;
@@ -172,11 +172,11 @@ class HomogeneousViewport extends RenderObjectWrapper {
     return itemCount != null ? itemCount * itemExtent : double.INFINITY;
   }
 
-  double getMinCrossAxisDimension(BoxConstraints constraints) {
+  double getMinCrossAxisExtent(BoxConstraints constraints) {
     return 0.0;
   }
 
-  double getMaxCrossAxisDimension(BoxConstraints constraints) {
+  double getMaxCrossAxisExtent(BoxConstraints constraints) {
     if (direction == ScrollDirection.vertical)
       return constraints.maxWidth;
     return constraints.maxHeight;

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

@@ -98,17 +98,17 @@ class MixedViewport extends RenderObjectWrapper {
     // create it, because the render object is empty so it will not matter
     RenderBlockViewport result = new RenderBlockViewport();
     result.callback = layout;
-    result.totalExtentCallback = _noIntrinsicDimensions;
-    result.maxCrossAxisDimensionCallback = _noIntrinsicDimensions;
-    result.minCrossAxisDimensionCallback = _noIntrinsicDimensions;
+    result.totalExtentCallback = _noIntrinsicExtent;
+    result.maxCrossAxisExtentCallback = _noIntrinsicExtent;
+    result.minCrossAxisExtentCallback = _noIntrinsicExtent;
     return result;
   }
 
   void remove() {
     renderObject.callback = null;
     renderObject.totalExtentCallback = null;
-    renderObject.maxCrossAxisDimensionCallback = null;
-    renderObject.minCrossAxisDimensionCallback = null;
+    renderObject.maxCrossAxisExtentCallback = null;
+    renderObject.minCrossAxisExtentCallback = null;
     super.remove();
     _childrenByKey.clear();
     layoutState._dirty = true;
@@ -140,7 +140,7 @@ class MixedViewport extends RenderObjectWrapper {
     assert(renderObject == this.renderObject); // TODO(ianh): Remove this once the analyzer is cleverer
   }
 
-  double _noIntrinsicDimensions(BoxConstraints constraints) {
+  double _noIntrinsicExtent(BoxConstraints constraints) {
     assert(() {
       'MixedViewport does not support returning intrinsic dimensions. ' +
       'Calculating the intrinsic dimensions would require walking the entire child list, ' +
@@ -330,7 +330,7 @@ class MixedViewport extends RenderObjectWrapper {
         'all the children. You probably want to put the MixedViewport inside a Container with a fixed width.' is String);
     }
     final double endOffset = startOffset + extent;
-    
+
     BoxConstraints innerConstraints;
     if (direction == ScrollDirection.vertical) {
       innerConstraints = new BoxConstraints.tightFor(width: constraints.constrainWidth());