Document additional cases (#137957)

Fixes https://github.com/flutter/flutter/issues/137924
Fixes https://github.com/flutter/flutter/issues/136885

The framework defaults to keeping the widget tree alive and ready to render regardless of application lifecycle events such as showing or hiding a view controller.

Add-to-app developers may be surprised by this, and tend to file bugs asking why `dispose` isn't called when the view is dismissed (or why memory usage is higher than expected after dismissing Flutter UI).

Adds documentation to explain the limitation and what to do instead.

/cc @zanderso @chinmaygarde @jonahwilliams @jason-simmons since we were discussing this in triage.

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

@@ -1184,6 +1184,21 @@ mixin WidgetsBinding on BindingBase, ServicesBinding, SchedulerBinding, GestureB
 /// To listen for platform shutdown messages (and other lifecycle changes),
 /// consider the [AppLifecycleListener] API.
 ///
+/// ## Dismissing Flutter UI via platform native methods
+///
+/// {@template flutter.widgets.runApp.dismissal}
+/// An application may have both Flutter and non-Flutter UI in it. If the
+/// application calls non-Flutter methods to remove Flutter based UI such as
+/// platform native API to manipulate the platform native navigation stack,
+/// the framework does not know if the developer intends to eagerly free
+/// resources or not. The widget tree remains mounted and ready to render
+/// as soon as it is displayed again.
+///
+/// To release resources more eagerly, establish a [platform channel](https://flutter.dev/platform-channels/)
+/// and use it to call [runApp] with a widget such as [SizedBox.shrink] when
+/// the framework should dispose of the active widget tree.
+/// {@endtemplate}
+///
 /// See also:
 ///
 ///  * [WidgetsBinding.attachRootWidget], which creates the root widget for the

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

@@ -1303,13 +1303,18 @@ abstract class State<T extends StatefulWidget> with Diagnosticable {
   /// Implementations of this method should end with a call to the inherited
   /// method, as in `super.dispose()`.
   ///
-  /// ## Application shutdown
+  /// ## Caveats
   ///
-  /// This method is _not_ invoked when the application shuts down, because
+  /// This method is _not_ invoked at times where a developer might otherwise
-  /// there is no way to predict when that will happen. For example, a user's
+  /// expect it, such as application shutdown or dismissal via platform
-  /// battery could catch fire, or the user could drop the device into a
+  /// native methods.
-  /// swimming pool, or the operating system could unilaterally terminate the
+  ///
-  /// application process due to memory pressure.
+  /// ### Application shutdown
+  ///
+  /// There is no way to predict when application shutdown will happen. For
+  /// example, a user's battery could catch fire, or the user could drop the
+  /// device into a swimming pool, or the operating system could unilaterally
+  /// terminate the application process due to memory pressure.
   ///
   /// Applications are responsible for ensuring that they are well-behaved
   /// even in the face of a rapid unscheduled termination.
@@ -1320,6 +1325,10 @@ abstract class State<T extends StatefulWidget> with Diagnosticable {
   /// To listen for platform shutdown messages (and other lifecycle changes),
   /// consider the [AppLifecycleListener] API.
   ///
+  /// ### Dismissing Flutter UI via platform native methods
+  ///
+  /// {@macro flutter.widgets.runApp.dismissal}
+  ///
   /// See also:
   ///
   ///  * [deactivate], which is called prior to [dispose].