From cb4147cf732b7a4124b4ba5ea9a9c46306080f3b Mon Sep 17 00:00:00 2001
From: Kate Lovett <katelovett@google.com>
Date: Tue, 31 Mar 2020 13:11:02 -0700
Subject: [PATCH] Doc Improvements (#53377)

---
 packages/flutter/lib/src/widgets/basic.dart   |  5 ++-
 .../lib/src/widgets/overscroll_indicator.dart | 41 +++++++++++++++++++
 .../flutter/lib/src/widgets/scroll_view.dart  |  3 +-
 3 files changed, 46 insertions(+), 3 deletions(-)

diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart
index c9522f88b2..cdfecd70ef 100644
--- a/packages/flutter/lib/src/widgets/basic.dart
+++ b/packages/flutter/lib/src/widgets/basic.dart
@@ -2013,8 +2013,9 @@ class CustomMultiChildLayout extends MultiChildRenderObjectWidget {
 ///
 /// If given a child, this widget forces its child to have a specific width
 /// and/or height (assuming values are permitted by this widget's parent). If
-/// either the width or height is null, this widget will size itself to match
-/// the child's size in that dimension.
+/// either the width or height is null, this widget will try to size itself to
+/// match the child's size in that dimension. If the child's size depends on the
+/// size of its parent, the height and width must be provided.
 ///
 /// If not given a child, [SizedBox] will try to size itself as close to the
 /// specified height and width as possible given the parent's constraints. If
diff --git a/packages/flutter/lib/src/widgets/overscroll_indicator.dart b/packages/flutter/lib/src/widgets/overscroll_indicator.dart
index ec610e50f1..aec670bcce 100644
--- a/packages/flutter/lib/src/widgets/overscroll_indicator.dart
+++ b/packages/flutter/lib/src/widgets/overscroll_indicator.dart
@@ -32,6 +32,47 @@ import 'ticker_provider.dart';
 /// (e.g., Android) that commonly use this type of overscroll indication.
 ///
 /// In a [MaterialApp], the edge glow color is the [ThemeData.accentColor].
+///
+/// When building a [CustomScrollView] with a [GlowingOverscrollIndicator], the
+/// indicator will apply to the entire scrollable area, regardless of what
+/// slivers the CustomScrollView contains.
+///
+/// For example, if your CustomScrollView contains a SliverAppBar in the first
+/// position, the GlowingOverscrollIndicator will overlay the SliverAppBar. To
+/// manipulate the position of the GlowingOverscrollIndicator in this case, use
+/// a [NestedScrollView].
+///
+/// {@tool dartpad --template=stateless_widget_scaffold}
+///
+/// This example demonstrates how to use a [NestedScrollView] to manipulate the
+/// placement of a [GlowingOverscrollIndicator] when building a
+/// [CustomScrollView]. Drag the scrollable to see the bounds of the overscroll
+/// indicator.
+///
+/// ```dart
+/// Widget build(BuildContext context) {
+///   return NestedScrollView(
+///     headerSliverBuilder: (BuildContext context, bool innerBoxIsScrolled) {
+///       return <Widget>[
+///         SliverAppBar(title: Text('Custom NestedScrollViews')),
+///       ];
+///     },
+///     body: CustomScrollView(
+///       slivers: <Widget>[
+///         SliverToBoxAdapter(
+///           child: Container(
+///             color: Colors.amberAccent,
+///             height: 100,
+///             child: Center(child: Text('Glow all day!')),
+///           ),
+///         ),
+///         SliverFillRemaining(child: FlutterLogo()),
+///       ],
+///     ),
+///   );
+/// }
+/// ```
+/// {@end-tool}
 class GlowingOverscrollIndicator extends StatefulWidget {
   /// Creates a visual indication that a scroll view has overscrolled.
   ///
diff --git a/packages/flutter/lib/src/widgets/scroll_view.dart b/packages/flutter/lib/src/widgets/scroll_view.dart
index e19a7c15e0..51882cd96a 100644
--- a/packages/flutter/lib/src/widgets/scroll_view.dart
+++ b/packages/flutter/lib/src/widgets/scroll_view.dart
@@ -205,7 +205,8 @@ abstract class ScrollView extends StatelessWidget {
   ///
   /// Children after [center] will be placed in the [axisDirection] relative to
   /// the [center]. Children before [center] will be placed in the opposite of
-  /// the [axisDirection] relative to the [center].
+  /// the [axisDirection] relative to the [center]. This makes the [center] the
+  /// inflection point of the growth direction.
   ///
   /// The [center] must be the key of one of the slivers built by [buildSlivers].
   ///