sticky_header [nfc]: Doc overflow behavior and paint-order constraints

Author: gnprice

lib/widgets/sticky_header.dart

@@ -312,6 +312,29 @@ enum _HeaderGrowthPlacement {
 ///
 /// This widget takes most of its behavior from [SliverList],
 /// but adds sticky headers as described at [StickyHeaderListView].
+///
+/// ## Overflow across slivers
+///
+/// When the list item that controls the sticky header has
+/// [StickyHeaderItem.allowOverflow] true, the header will be permitted
+/// to overflow not only the item but this whole sliver.
+///
+/// The caller is responsible for arranging the paint order between slivers
+/// so that this works correctly: a sliver that might overflow must be painted
+/// after any sliver it might overflow onto.
+/// For example if [headerPlacement] puts headers at the left of the viewport
+/// (and any items with [StickyHeaderItem.allowOverflow] true are present),
+/// then this [SliverStickyHeaderList] must paint after any slivers that appear
+/// to the right of this sliver.
+///
+/// At present the only off-the-shelf way to accomplish that is to
+/// have every [SliverStickyHeaderList] grow away from the header edge:
+/// so if [headerPlacement] is [HeaderPlacement.scrollingEnd],
+/// then [CustomScrollView.center] must point to a sliver
+/// after every [SliverStickyHeaderList] in [CustomScrollView.slivers],
+/// and if [HeaderPlacement.scrollingStart] then
+/// [CustomScrollView.center] must not point to any sliver
+/// after the first [SliverStickyHeaderList].
 class SliverStickyHeaderList extends RenderObjectWidget {
   SliverStickyHeaderList({
     super.key,