The documentation will continue until morale improves (#10978)

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();
   }

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,