More clarifications on mutating Widget's children (#46725)
diff --git a/packages/flutter/lib/src/widgets/framework.dart b/packages/flutter/lib/src/widgets/framework.dart
index f6084e4..6252327 100644
--- a/packages/flutter/lib/src/widgets/framework.dart
+++ b/packages/flutter/lib/src/widgets/framework.dart
@@ -1729,9 +1729,61 @@
/// The widgets below this widget in the tree.
///
- /// If this list is going to be mutated, it is usually wise to put [Key]s on
- /// the widgets, so that the framework can match old configurations to new
- /// configurations and maintain the underlying render objects.
+ /// 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 `someMultiChildRenderObjectWidget.children.add(...)` or
+ /// as the example code below will result in incorrect behaviors. Whenever the
+ /// children list is modified, a new list object should be provided.
+ ///
+ /// ```dart
+ /// class SomeWidgetState extends State<SomeWidget> {
+ /// List<Widget> _children;
+ ///
+ /// void initState() {
+ /// _children = [];
+ /// }
+ ///
+ /// void someHandler() {
+ /// setState(() {
+ /// _children.add(...);
+ /// });
+ /// }
+ ///
+ /// Widget build(...) {
+ /// // Reusing `List<Widget> _children` here is problematic.
+ /// return Row(children: _children);
+ /// }
+ /// }
+ /// ```
+ ///
+ /// 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: ...));
+ /// });
+ /// }
+ ///
+ /// Widget build(...) {
+ /// // Always create a new list of children as a Widget is immutable.
+ /// return Row(children: List.from(_children));
+ /// }
+ /// }
+ /// ```
final List<Widget> children;
@override
