From 5f18d0f72115da7a1d141bf182d98f24f54e3830 Mon Sep 17 00:00:00 2001
From: xster <xiao@xster.net>
Date: Wed, 17 Apr 2019 13:52:10 -0700
Subject: [PATCH] Clarify various CupertinoTabView docs (#31109)

---
 packages/flutter/lib/src/cupertino/tab_scaffold.dart | 10 ++++++++--
 packages/flutter/lib/src/cupertino/tab_view.dart     |  9 +++++++++
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/packages/flutter/lib/src/cupertino/tab_scaffold.dart b/packages/flutter/lib/src/cupertino/tab_scaffold.dart
index b478eb81e2..b5da868907 100644
--- a/packages/flutter/lib/src/cupertino/tab_scaffold.dart
+++ b/packages/flutter/lib/src/cupertino/tab_scaffold.dart
@@ -20,8 +20,14 @@ import 'theme.dart';
 /// pages as there are [tabBar.items]. Inactive tabs will be moved [Offstage]
 /// and their animations disabled.
 ///
-/// Use [CupertinoTabView] as the content of each tab to support tabs with parallel
-/// navigation state and history.
+/// Use [CupertinoTabView] as the root widget of each tab to support tabs with
+/// parallel navigation state and history. Since each [CupertinoTabView] contains
+/// a [Navigator], rebuilding the [CupertinoTabView] with a different
+/// [WidgetBuilder] instance in [CupertinoTabView.builder] will not recreate
+/// the [CupertinoTabView]'s navigation stack or update its UI. To update the
+/// contents of the [CupertinoTabView] after it's built, trigger a rebuild
+/// (via [State.setState], for instance) from its descendant rather than from
+/// its ancestor.
 ///
 /// {@tool sample}
 ///
diff --git a/packages/flutter/lib/src/cupertino/tab_view.dart b/packages/flutter/lib/src/cupertino/tab_view.dart
index 41f36fa315..1984c9e963 100644
--- a/packages/flutter/lib/src/cupertino/tab_view.dart
+++ b/packages/flutter/lib/src/cupertino/tab_view.dart
@@ -57,6 +57,15 @@ class CupertinoTabView extends StatefulWidget {
   ///
   /// If a [builder] is specified, then [routes] must not include an entry for `/`,
   /// as [builder] takes its place.
+  ///
+  /// Rebuilding a [CupertinoTabView] with a different [builder] will not clear
+  /// its current navigation stack or update its descendant. Instead, trigger a
+  /// rebuild from a descendant in its subtree. This can be done via methods such
+  /// as:
+  ///
+  ///  * Calling [State.setState] on a descendant [StatefulWidget]'s [State]
+  ///  * Modifying an [InheritedWidget] that a descendant registered itself
+  ///    as a dependent to.
   final WidgetBuilder builder;
 
   /// A key to use when building this widget's [Navigator].