Improve the document of pageView and ListView (#68001)

packages/flutter/lib/src/widgets/page_view.dart

@@ -589,6 +589,10 @@ class PageView extends StatefulWidget {
   /// child that could possibly be displayed in the page view, instead of just
   /// those children that are actually visible.
   ///
+  /// Like other widgets in the framework, this widget expects that
+  /// the [children] list will not be mutated after it has been passed in here.
+  /// See the documentation at [SliverChildListDelegate.children] for more details.
+  ///
   /// {@template flutter.widgets.pageView.allowImplicitScrolling}
   /// The [allowImplicitScrolling] parameter must not be null. If true, the
   /// [PageView] will participate in accessibility scrolling more like a

packages/flutter/lib/src/widgets/scroll_view.dart

@@ -1042,6 +1042,10 @@ class ListView extends BoxScrollView {
   /// child that could possibly be displayed in the list view instead of just
   /// those children that are actually visible.
   ///
+  /// Like other widgets in the framework, this widget expects that
+  /// the [children] list will not be mutated after it has been passed in here.
+  /// See the documentation at [SliverChildListDelegate.children] for more details.
+  ///
   /// It is usually more efficient to create children on demand using
   /// [ListView.builder] because it will create the widget children lazily as necessary.
   ///

packages/flutter/lib/src/widgets/sliver.dart

@@ -628,6 +628,42 @@ class SliverChildListDelegate extends SliverChildDelegate {
   final SemanticIndexCallback semanticIndexCallback;
 
   /// The widgets to display.
+  ///
+  /// If this list is going to be mutated, it is usually wise to put a [Key] on
+  /// each of the child widgets, so that the framework can match old
+  /// configurations to new configurations and maintain the underlying render
+  /// objects.
+  ///
+  /// Also, a [Widget] in Flutter is immutable, so directly modifying the
+  /// [children] such as `someWidget.children.add(...)` or
+  /// passing a reference of the original list value to the [children] parameter
+  /// will result in incorrect behaviors. Whenever the
+  /// children list is modified, a new list object should be provided.
+  ///
+  /// The following code corrects the problem mentioned above.
+  ///
+  /// ```dart
+  /// class SomeWidgetState extends State<SomeWidget> {
+  ///   List<Widget> _children;
+  ///
+  ///   void initState() {
+  ///     _children = [];
+  ///   }
+  ///
+  ///   void someHandler() {
+  ///     setState(() {
+  ///       // The key here allows Flutter to reuse the underlying render
+  ///       // objects even if the children list is recreated.
+  ///       _children.add(ChildWidget(key: UniqueKey()));
+  ///     });
+  ///   }
+  ///
+  ///   Widget build(BuildContext context) {
+  ///     // Always create a new list of children as a Widget is immutable.
+  ///     return PageView(children: List<Widget>.from(_children));
+  ///   }
+  /// }
+  /// ```
   final List<Widget> children;
 
   /// A map to cache key to index lookup for children.