diff --git a/packages/flutter/lib/src/cupertino/refresh.dart b/packages/flutter/lib/src/cupertino/refresh.dart
index 9664865d3d..7a76a478ad 100644
--- a/packages/flutter/lib/src/cupertino/refresh.dart
+++ b/packages/flutter/lib/src/cupertino/refresh.dart
@@ -242,7 +242,9 @@ typedef Future<void> RefreshCallback();
 /// Only one refresh can be triggered until the previous refresh has completed
 /// and the indicator sliver has retracted at least 90% of the way back.
 ///
-/// Can only be used in downward scrolling vertical lists.
+/// Can only be used in downward-scrolling vertical lists that overscrolls. In
+/// other words, refreshes can't be triggered with lists using
+/// [ClampingScrollPhysics].
 ///
 /// See also:
 ///
diff --git a/packages/flutter/lib/src/material/refresh_indicator.dart b/packages/flutter/lib/src/material/refresh_indicator.dart
index 19792f4779..2bc78dace8 100644
--- a/packages/flutter/lib/src/material/refresh_indicator.dart
+++ b/packages/flutter/lib/src/material/refresh_indicator.dart
@@ -74,7 +74,12 @@ enum _RefreshIndicatorMode {
 ///
 ///  * <https://material.google.com/patterns/swipe-to-refresh.html>
 ///  * [RefreshIndicatorState], can be used to programmatically show the refresh indicator.
-///  * [RefreshProgressIndicator].
+///  * [RefreshProgressIndicator], widget used by [RefreshIndicator] to show
+///    the inner circular progress spinner during refreshes.
+///  * [CupertinoRefreshControl], an iOS equivalent of the pull-to-refresh pattern.
+///    Must be used as a sliver inside a [CustomScrollView] instead of wrapping
+///    around a [ScrollView] because it's a part of the scrollable instead of
+///    being overlaid on top of it.
 class RefreshIndicator extends StatefulWidget {
   /// Creates a refresh indicator.
   ///