Complete docs for RenderObject (#4266)

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

@@ -41,9 +41,28 @@ enum PerformanceOverlayOption {
   visualizeEngineStatistics,
 }
 
+/// Displays performance statistics.
+///
+/// The overlay show two time series. The first shows how much time was required
+/// on this thread to produce each frame. The second shows how much time was
+/// required on the GPU thread to produce each frame. Ideally, both these values
+/// would be less than the total frame budget for the hardware on which the app
+/// is running. For example, if the hardware has a screen that updates at 60 Hz,
+/// each thread should ideally spend less than 16ms producing each frame. This
+/// ideal condition is indicated by a green vertical line for each thread.
+/// Otherwise, the performance overlay shows a red vertical line.
+///
+/// The simplest way to show the performance overlay is to set
+/// [MaterialApp.showPerformanceOverlay] or [WidgetsApp.showPerformanceOverlay]
+/// to `true`.
 class RenderPerformanceOverlay extends RenderBox {
-  RenderPerformanceOverlay({ int optionsMask: 0, int rasterizerThreshold: 0 })
-    : _optionsMask = optionsMask,
+  /// Creates a performance overlay render object.
+  ///
+  /// The [optionsMask] and [rasterizerThreshold] arguments must not be null.
+  RenderPerformanceOverlay({
+    int optionsMask: 0,
+    int rasterizerThreshold: 0
+  }) : _optionsMask = optionsMask,
       _rasterizerThreshold = rasterizerThreshold;
 
   /// The mask is created by shifting 1 by the index of the specific
@@ -51,6 +70,7 @@ class RenderPerformanceOverlay extends RenderBox {
   int get optionsMask => _optionsMask;
   int _optionsMask;
   set optionsMask(int mask) {
+    assert(mask != null);
     if (mask == _optionsMask)
       return;
     _optionsMask = mask;
@@ -63,6 +83,7 @@ class RenderPerformanceOverlay extends RenderBox {
   int get rasterizerThreshold => _rasterizerThreshold;
   int _rasterizerThreshold;
   set rasterizerThreshold (int threshold) {
+    assert(threshold != null);
     if (threshold == _rasterizerThreshold)
       return;
     _rasterizerThreshold = threshold;

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

@@ -91,6 +91,9 @@ abstract class RenderShiftedBox extends RenderBox with RenderObjectWithChildMixi
 /// 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 {
+  /// Creates a render object that insets its child.
+  ///
+  /// The [padding] argument must not be null and must have non-negative insets.
   RenderPadding({
     EdgeInsets padding,
     RenderBox child
@@ -219,12 +222,16 @@ class RenderPadding extends RenderShiftedBox {
   }
 }
 
+/// Abstract class for one-child-layout render boxes that use a
+/// [FractionalOffset] to align their children.
 abstract class RenderAligningShiftedBox extends RenderShiftedBox {
+  /// Initializes member variables for subclasses.
+  ///
+  /// The [alignment] argument must not be null.
   RenderAligningShiftedBox({
-    RenderBox child,
-    FractionalOffset alignment: FractionalOffset.center
-  }) : _alignment = alignment,
-       super(child) {
+    FractionalOffset alignment: FractionalOffset.center,
+    RenderBox child
+  }) : _alignment = alignment, super(child) {
     assert(alignment != null && alignment.dx != null && alignment.dy != null);
   }
 
@@ -274,7 +281,7 @@ abstract class RenderAligningShiftedBox extends RenderShiftedBox {
   }
 }
 
-/// Aligns its child box within itself.
+/// Positions its child using a [FractionalOffset].
 ///
 /// 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,
@@ -285,6 +292,7 @@ abstract class RenderAligningShiftedBox extends RenderShiftedBox {
 /// dimensions. Using widthFactor and heightFactor you can force this latter
 /// behavior in all cases.
 class RenderPositionedBox extends RenderAligningShiftedBox {
+  /// Creates a render object that positions its child.
   RenderPositionedBox({
     RenderBox child,
     double widthFactor,
@@ -427,6 +435,7 @@ class RenderPositionedBox extends RenderAligningShiftedBox {
 /// child inside a larger parent, use [RenderPositionedBox] and
 /// [RenderConstrainedBox] rather than RenderOverflowBox.
 class RenderConstrainedOverflowBox extends RenderAligningShiftedBox {
+  /// Creates a render object that lets its child overflow itself.
   RenderConstrainedOverflowBox({
     RenderBox child,
     double minWidth,
@@ -543,9 +552,12 @@ class RenderConstrainedOverflowBox extends RenderAligningShiftedBox {
   }
 }
 
-/// A render box that's a specific size but passes its original constraints
+/// A render box that is a specific size but passes its original constraints
 /// through to its child, which will probably overflow.
 class RenderSizedOverflowBox extends RenderAligningShiftedBox {
+  /// Creates a render box of a given size that lets its child overflow.
+  ///
+  /// The [requestedSize] argument must not be null.
   RenderSizedOverflowBox({
     RenderBox child,
     Size requestedSize,
@@ -617,6 +629,10 @@ class RenderSizedOverflowBox extends RenderAligningShiftedBox {
 ///
 /// It then tries to size itself to the size of its child.
 class RenderFractionallySizedOverflowBox extends RenderAligningShiftedBox {
+  /// Creates a render box that sizes its child to a fraction of the total available space.
+  ///
+  /// If non-null, the [widthFactor] and [heightFactor] arguments must be
+  /// non-negative.
   RenderFractionallySizedOverflowBox({
     RenderBox child,
     double widthFactor,
@@ -755,6 +771,9 @@ class SingleChildLayoutDelegate {
 /// of the parent, but the size of the parent cannot depend on the size of the
 /// child.
 class RenderCustomSingleChildLayoutBox extends RenderShiftedBox {
+  /// Creates a render box that defers its layout to a delgate.
+  ///
+  /// The [delegate] argument must not be null.
   RenderCustomSingleChildLayoutBox({
     RenderBox child,
     SingleChildLayoutDelegate delegate

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

@@ -48,6 +48,9 @@ class ViewConfiguration {
 /// bootstrapping the rendering pipeline. The view has a unique child
 /// [RenderBox], which is required to fill the entire output surface.
 class RenderView extends RenderObject with RenderObjectWithChildMixin<RenderBox> {
+  /// Creates the root of the render tree.
+  ///
+  /// Typically created by the binding (e.g., [RendererBinding]).
   RenderView({
     RenderBox child,
     this.timeForRotation: const Duration(microseconds: 83333),
@@ -115,6 +118,13 @@ class RenderView extends RenderObject with RenderObjectWithChildMixin<RenderBox>
     assert(false); // nobody tells the screen to rotate, the whole rotate() dance is started from our performResize()
   }
 
+  /// Determines the set of render objects located at the given position.
+  ///
+  /// Returns true if the given point is contained in this render object or one
+  /// of its descendants. Adds any render objects that contain the point to the
+  /// given hit test result.
+  ///
+  /// The [position] argument is in the coordinate system of the render view.
   bool hitTest(HitTestResult result, { Point position }) {
     if (child != null)
       child.hitTest(result, position: position);

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

@@ -13,8 +13,9 @@ import 'framework.dart';
 /// required on the GPU thread to produce each frame. Ideally, both these values
 /// would be less than the total frame budget for the hardware on which the app
 /// is running. For example, if the hardware has a screen that updates at 60 Hz,
-/// each thread should ideally spend less than 16 ms producing each frame. This
+/// each thread should ideally spend less than 16ms producing each frame. This
 /// ideal condition is indicated by a green vertical line for each thread.
+/// Otherwise, the performance overlay shows a red vertical line.
 ///
 /// The simplest way to show the performance overlay is to set
 /// [MaterialApp.showPerformanceOverlay] or [WidgetsApp.showPerformanceOverlay]