From cb4a54db8fb3726bf4293b9cc5cb12ce16883803 Mon Sep 17 00:00:00 2001
From: Ian Hickson <ian@hixie.ch>
Date: Tue, 27 Jun 2017 16:19:59 -0700
Subject: [PATCH] The documentation will continue until morale improves
 (#10978)

---
 .../flutter/lib/src/rendering/proxy_box.dart   |  6 ++++++
 .../rendering/sliver_persistent_header.dart    | 18 ++++++++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/packages/flutter/lib/src/rendering/proxy_box.dart b/packages/flutter/lib/src/rendering/proxy_box.dart
index 38b5bb5011..b4d3888365 100644
--- a/packages/flutter/lib/src/rendering/proxy_box.dart
+++ b/packages/flutter/lib/src/rendering/proxy_box.dart
@@ -3178,6 +3178,12 @@ class RenderFollowerLayer extends RenderProxyBox {
   /// The layer we created when we were last painted.
   FollowerLayer _layer;
 
+  /// Return the transform that was used in the last composition phase, if any.
+  ///
+  /// If the [FollowerLayer] has not yet been created, was never composited, or
+  /// was unable to determine the transform (see
+  /// [FollowerLayer.getLastTransform]), this returns the identity matrix (see
+  /// [new Matrix4.identity].
   Matrix4 getCurrentTransform() {
     return _layer?.getLastTransform() ?? new Matrix4.identity();
   }
diff --git a/packages/flutter/lib/src/rendering/sliver_persistent_header.dart b/packages/flutter/lib/src/rendering/sliver_persistent_header.dart
index e969582f6a..4a1bae5de6 100644
--- a/packages/flutter/lib/src/rendering/sliver_persistent_header.dart
+++ b/packages/flutter/lib/src/rendering/sliver_persistent_header.dart
@@ -16,6 +16,21 @@ import 'object.dart';
 import 'sliver.dart';
 import 'viewport_offset.dart';
 
+/// A base class for slivers that have a [RenderBox] child which scrolls
+/// normally, except that when it hits the leading edge (typically the top) of
+/// the viewport, it shrinks to a minimum size ([minExtent]).
+///
+/// This class primarily provides helpers for managing the child, in particular:
+///
+///  * [layoutChild], which applies min and max extents and a scroll offset to
+///    lay out the child. This is normally called from [performLayout].
+///
+///  * [childExtent], to convert the child's box layout dimensions to the sliver
+///    geometry model.
+///
+///  * hit testing, painting, and other details of the sliver protocol.
+///
+/// Subclasses must implement [performLayout], [minExtent], and [maxExtent].
 abstract class RenderSliverPersistentHeader extends RenderSliver with RenderObjectWithChildMixin<RenderBox>, RenderSliverHelpers {
   RenderSliverPersistentHeader({ RenderBox child }) {
     this.child = child;
@@ -286,6 +301,9 @@ class FloatingHeaderSnapConfiguration {
   final Duration duration;
 }
 
+/// A sliver with a [RenderBox] child which shrinks and scrolls like a
+/// [RenderSliverScrollingPersistentHeader], but immediately comes back when the
+/// user scrolls in the reverse direction.
 abstract class RenderSliverFloatingPersistentHeader extends RenderSliverPersistentHeader {
   RenderSliverFloatingPersistentHeader({
     RenderBox child,