Updated Stateless and Stateful widget docstrings (#95407)
diff --git a/packages/flutter/lib/src/widgets/framework.dart b/packages/flutter/lib/src/widgets/framework.dart
index 1ad1e6d..ca248ba 100644
--- a/packages/flutter/lib/src/widgets/framework.dart
+++ b/packages/flutter/lib/src/widgets/framework.dart
@@ -438,6 +438,14 @@
/// * Use `const` widgets where possible, and provide a `const` constructor for
/// the widget so that users of the widget can also do so.
///
+/// * When trying to create a reusable piece of UI, prefer using a widget
+/// rather than a helper method. For example, if there was a function used to
+/// build a widget, a [State.setState] call would require Flutter to entirely
+/// rebuild the returned wrapping widget. If a [Widget] was used instead,
+/// Flutter would be able to efficiently re-render only those parts that
+/// really need to be updated. Even better, if the created widget is `const`,
+/// Flutter would short-circuit most of the rebuild work.
+///
/// * Consider refactoring the stateless widget into a stateful widget so that
/// it can use some of the techniques described at [StatefulWidget], such as
/// caching common parts of subtrees and using [GlobalKey]s when changing the
@@ -646,11 +654,20 @@
/// efficient for a widget to be re-used than for a new (but
/// identically-configured) widget to be created. Factoring out the stateful
/// part into a widget that takes a child argument is a common way of doing
-/// this.
+/// this. Another caching strategy consists of assigning a widget to a
+/// `final` state variable which can be used in the build method.
///
/// * Use `const` widgets where possible. (This is equivalent to caching a
/// widget and re-using it.)
///
+/// * When trying to create a reusable piece of UI, prefer using a widget
+/// rather than a helper method. For example, if there was a function used to
+/// build a widget, a [State.setState] call would require Flutter to entirely
+/// rebuild the returned wrapping widget. If a [Widget] was used instead,
+/// Flutter would be able to efficiently re-render only those parts that
+/// really need to be updated. Even better, if the created widget is `const`,
+/// Flutter would short-circuit most of the rebuild work.
+///
/// * Avoid changing the depth of any created subtrees or changing the type of
/// any widgets in the subtree. For example, rather than returning either the
/// child or the child wrapped in an [IgnorePointer], always wrap the child
