From a4ee70c0752fa4b09baad3a39a1cb04816e067ad Mon Sep 17 00:00:00 2001
From: Hixie <github.com@spam.hixie.ch>
Date: Wed, 16 Mar 2016 14:30:11 -0700
Subject: [PATCH] Flesh out rendering library top-level docs

---
 packages/flutter/lib/rendering.dart           | 14 +++++++++++
 .../flutter/lib/src/rendering/object.dart     | 23 +++++++++++++++++--
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/packages/flutter/lib/rendering.dart b/packages/flutter/lib/rendering.dart
index b65b09b466..6d1e26b354 100644
--- a/packages/flutter/lib/rendering.dart
+++ b/packages/flutter/lib/rendering.dart
@@ -3,6 +3,20 @@
 // found in the LICENSE file.
 
 /// The Flutter rendering tree.
+///
+/// The [RenderObject] hierarchy is used by the Flutter Widgets
+/// library to implement its layout and painting back-end. Generally,
+/// while you may use custom [RenderBox] classes for specific effects
+/// in your applications, most of the time your only interaction with
+/// the [RenderObject] hierarchy will be in debugging layout issues.
+///
+/// If you are developing your own library or application directly on
+/// top of the rendering library, then you will want to have a binding
+/// (see [BindingBase]). You can use [RenderingFlutterBinding], or you
+/// can create your own binding. If you create your own binding, it
+/// needs to import at least [Scheduler], [Gesturer], [Services], and
+/// [Renderer]. The rendering library does not automatically create a
+/// binding, but relies on one being initialized with those features.
 library rendering;
 
 export 'src/rendering/auto_layout.dart';
diff --git a/packages/flutter/lib/src/rendering/object.dart b/packages/flutter/lib/src/rendering/object.dart
index 266bc2ab67..d0f69eb1e4 100644
--- a/packages/flutter/lib/src/rendering/object.dart
+++ b/packages/flutter/lib/src/rendering/object.dart
@@ -662,8 +662,27 @@ class _ForkingSemanticsFragment extends _SemanticsFragment {
 
 /// An object in the render tree.
 ///
-/// Render objects have a reference to their parent but do not commit to a model
-/// for their children.
+/// The [RenderObject] class hierarchy is the core of the rendering
+/// library's reason for being.
+///
+/// [RenderObject]s have a [parent], and have a slot called
+/// [parentData] in which the parent [RenderObject] can store
+/// child-specific data, for example, the child position. The
+/// [RenderObject] class also implements the basic layout and paint
+/// protocols.
+///
+/// The [RenderObject] class, however, does not define a child model
+/// (e.g. whether a node has zero, one, or more children). It also
+/// doesn't define a coordinate system (e.g. whether children are
+/// positioned in cartesian coordinates, in polar coordinates, etc) or
+/// a specific layout protocol (e.g. whether the layout is
+/// width-in-height-out, or constraint-in-size-out, or whether the
+/// parent sets the size and position of the child before or after the
+/// child lays out, etc; or indeed whether the children are allowed to
+/// read their parent's [parentData] slot).
+///
+/// The [RenderBox] subclass introduces the opinion that the layout
+/// system uses cartesian coordinates.
 abstract class RenderObject extends AbstractNode implements HitTestTarget {
 
   RenderObject() {