Add more dartdocs for the sliver render objects (#8749)

This patch covers multi-box adaptor and the viewports.

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

@@ -1225,9 +1225,9 @@ abstract class RenderSliverHelpers implements RenderSliver {
 ///
 /// See also:
 ///
-/// - [RenderSliver], which explains more about the Sliver protocol.
-/// - [RenderBox], which explains more about the Box protocol.
-/// - [RenderViewport], which allows [RenderSliver] objects to be placed inside
+/// * [RenderSliver], which explains more about the Sliver protocol.
+/// * [RenderBox], which explains more about the Box protocol.
+/// * [RenderViewport], which allows [RenderSliver] objects to be placed inside
 ///   a [RenderBox] (the opposite of this class).
 class RenderSliverToBoxAdapter extends RenderSliver with RenderObjectWithChildMixin<RenderBox>, RenderSliverHelpers {
   /// Creates a [RenderSliver] that wraps a [RenderBox].

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

@@ -75,6 +75,17 @@ abstract class RenderSliverBoxChildManager {
   /// the child list after this function returns.
   void didAdoptChild(RenderBox child);
 
+  /// Called during layout to indicate whether this object provided insufficient
+  /// children for the [RenderSliverMultiBoxAdaptor] to fill the
+  /// [SliverConstraints.remainingPaintExtent].
+  ///
+  /// Typically called unconditionally at the start of layout with false and
+  /// then later called with true when the [RenderSliverMultiBoxAdaptor]
+  /// fails to create a child required to fill the
+  /// [SliverConstraints.remainingPaintExtent].
+  ///
+  /// Useful for subclasses to determine whether newly added children could
+  /// affect the visible contents of the [RenderSliverMultiBoxAdaptor].
   void setDidUnderflow(bool value);
 
   /// In debug mode, asserts that this manager is not expecting any
@@ -88,25 +99,47 @@ abstract class RenderSliverBoxChildManager {
   bool debugAssertChildListLocked() => true;
 }
 
+/// Parent data structure used by [RenderSliverMultiBoxAdaptor].
 class SliverMultiBoxAdaptorParentData extends SliverLogicalParentData with ContainerParentDataMixin<RenderBox> {
+  /// The index of this child according to the [RenderSliverBoxChildManager].
   int index;
 
   @override
   String toString() => 'index=$index; ${super.toString()}';
 }
 
-// /// The contract for adding and removing children from this render object is
-// /// more strict than for normal render objects:
-// ///
-// /// - Children can be removed except during a layout pass if they have already
-// ///   been laid out during that layout pass.
-// /// - Children cannot be added except during a call to [childManager], and
-// ///   then only if there is no child correspending to that index (or the child
-// ///   child corresponding to that index was first removed).
+/// A sliver with multiple box children.
+///
+/// [RenderSliverMultiBoxAdaptor] is a base class for slivers that have multiple
+/// box children. The children are managed by a [RenderSliverBoxChildManager],
+/// which lets subclasses create children lazily during layout. Typically
+/// subclasses will create only those children that are actually needed to fill
+/// the [SliverConstraints.remainingPaintExtent].
+///
+/// The contract for adding and removing children from this render object is
+/// more strict than for normal render objects:
+///
+/// * Children can be removed except during a layout pass if they have already
+///   been laid out during that layout pass.
+/// * Children cannot be added except during a call to [childManager], and
+///   then only if there is no child correspending to that index (or the child
+///   child corresponding to that index was first removed).
+///
+/// See also:
+///
+///  * [RenderSliverToBoxAdapter], which has a single box child.
+///  * [RenderSliverList], which places its children in a linear
+///    array.
+///  * [RenderSliverFixedExtentList], which places its children in a linear
+///    array with a fixed extent in the main axis.
+///  * [RenderSliverGrid], which places its children in arbitrary positions.
 abstract class RenderSliverMultiBoxAdaptor extends RenderSliver
   with ContainerRenderObjectMixin<RenderBox, SliverMultiBoxAdaptorParentData>,
        RenderSliverHelpers {
 
+  /// Creates a sliver with multiple box children.
+  ///
+  /// The [childManager] argument must not be null.
   RenderSliverMultiBoxAdaptor({
     @required RenderSliverBoxChildManager childManager
   }) : _childManager = childManager {
@@ -119,6 +152,12 @@ abstract class RenderSliverMultiBoxAdaptor extends RenderSliver
       child.parentData = new SliverMultiBoxAdaptorParentData();
   }
 
+  /// The delegate that manages the children of this object.
+  ///
+  /// Rather than having a concrete list of children, a
+  /// [RenderSliverMultiBoxAdaptor] uses a [RenderSliverBoxChildManager] to
+  /// create children during layout in order to fill the
+  /// [SliverConstraints.remainingPaintExtent].
   @protected
   RenderSliverBoxChildManager get childManager => _childManager;
   final RenderSliverBoxChildManager _childManager;
@@ -379,6 +418,10 @@ abstract class RenderSliverMultiBoxAdaptor extends RenderSliver
     }
   }
 
+  /// Asserts that the reified child list is not empty and has a contiguous
+  /// sequence of indices.
+  ///
+  /// Always returns true.
   bool debugAssertChildListIsNonEmptyAndContiguous() {
     assert(() {
       assert(firstChild != null);