Update docs for initstate(), didUpdateWidget(), dispose() (#27501)

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

@@ -44,6 +44,20 @@ export 'package:flutter/rendering.dart' show RenderObject, RenderBox, debugDumpR
 /// `children` property, and then provide the children to that widget.
 /// {@endtemplate}
 
+/// {@template flutter.widgets.subscriptions}
+/// If a [State]'s [build] method depends on an object that can itself
+/// change state, for example a [ChangeNotifier] or [Stream], or some
+/// other object to which one can subscribe to receive notifications, then
+/// be sure to subscribe and unsubscribe properly in [initState],
+/// [didUpdateWidget], and [dispose]:
+///
+///  * In [initState], subscribe to the object.
+///  * In [didUpdateWidget] unsubscribe from the old object and subscribe
+///    to the new one if the updated widget configuration requires
+///    replacing the object.
+///  * In [dispose], unsubscribe from the object.
+/// {@endtemplate}
+
 // KEYS
 
 /// A key that is only equal to itself.
@@ -982,12 +996,7 @@ abstract class State<T extends StatefulWidget> extends Diagnosticable {
   /// location at which this object was inserted into the tree (i.e., [context])
   /// or on the widget used to configure this object (i.e., [widget]).
   ///
-  /// If a [State]'s [build] method depends on an object that can itself change
-  /// state, for example a [ChangeNotifier] or [Stream], or some other object to
-  /// which one can subscribe to receive notifications, then the [State] should
-  /// subscribe to that object during [initState], unsubscribe from the old
-  /// object and subscribe to the new object when it changes in
-  /// [didUpdateWidget], and then unsubscribe from the object in [dispose].
+  /// {@macro flutter.widgets.subscriptions}
   ///
   /// You cannot use [BuildContext.inheritFromWidgetOfExactType] from this
   /// method. However, [didChangeDependencies] will be called immediately
@@ -1016,12 +1025,7 @@ abstract class State<T extends StatefulWidget> extends Diagnosticable {
   /// The framework always calls [build] after calling [didUpdateWidget], which
   /// means any calls to [setState] in [didUpdateWidget] are redundant.
   ///
-  /// If a [State]'s [build] method depends on an object that can itself change
-  /// state, for example a [ChangeNotifier] or [Stream], or some other object to
-  /// which one can subscribe to receive notifications, then the [State] should
-  /// subscribe to that object during [initState], unsubscribe from the old
-  /// object and subscribe to the new object when it changes in
-  /// [didUpdateWidget], and then unsubscribe from the object in [dispose].
+  /// {@macro flutter.widgets.subscriptions}
   ///
   /// If you override this, make sure your method starts with a call to
   /// super.didUpdateWidget(oldWidget).
@@ -1174,12 +1178,7 @@ abstract class State<T extends StatefulWidget> extends Diagnosticable {
   /// Subclasses should override this method to release any resources retained
   /// by this object (e.g., stop any active animations).
   ///
-  /// If a [State]'s [build] method depends on an object that can itself change
-  /// state, for example a [ChangeNotifier] or [Stream], or some other object to
-  /// which one can subscribe to receive notifications, then the [State] should
-  /// subscribe to that object during [initState], unsubscribe from the old
-  /// object and subscribe to the new object when it changes in
-  /// [didUpdateWidget], and then unsubscribe from the object in [dispose].
+  /// {@macro flutter.widgets.subscriptions}
   ///
   /// If you override this, make sure to end your method with a call to
   /// super.dispose().