Update docs.

Author: gspencergoog

lib/ui/platform_dispatcher.dart

@@ -1642,19 +1642,37 @@ class FrameTiming {
 
 /// States that an application can be in once it is running.
 ///
+/// States not supported on a platform will be synthesized by the framework when
+/// transitioning between states which are supported, so that all
+/// implementations share the same state machine.
+///
 /// The current application state can be obtained from
-/// [SchedulerBinding.instance.lifecycleState], and changes in state can be
+/// [SchedulerBinding.instance.lifecycleState], and changes to the state can be
 /// observed by creating an [AppLifecycleListener], or by using a
 /// [WidgetsBindingObserver] by overriding the
 /// [WidgetsBindingObserver.didChangeAppLifecycleState] method.
 ///
-/// Applications should not expect to always receive all possible notifications.
+/// Applications should not rely on always receiving all possible notifications.
 ///
 /// For example, if the application is killed with a task manager, a kill
 /// signal, the user pulls the power from the device, or there is a rapid
 /// unscheduled disassembly of the device, no notification will be sent before
 /// the application is suddenly terminated, and some states may be skipped.
 enum AppLifecycleState {
+  /// The application is still hosted by a Flutter engine but is detached from
+  /// any host views.
+  ///
+  /// The application defaults to this state before it initializes, and can be
+  /// in this state (on Android and iOS only) after all views have been
+  /// detached.
+  ///
+  /// When the application is in this state, the engine is running without a
+  /// view.
+  ///
+  /// This state is only entered on iOS and Android, although on all platforms
+  /// it is the default state before the application begins running.
+  detached,
+
   /// The application is in the default running mode for a running application
   /// that has input focus and is visible.
   resumed,
@@ -1705,20 +1723,6 @@ enum AppLifecycleState {
   ///
   /// This state is only entered on iOS and Android.
   paused,
-
-  /// The application is still hosted by a Flutter engine but is detached from
-  /// any host views.
-  ///
-  /// The application defaults to this state before it initializes, and can be
-  /// in this state (on Android and iOS only) after all views have been
-  /// detached.
-  ///
-  /// When the application is in this state, the engine is running without a
-  /// view.
-  ///
-  /// This state is only entered on iOS and Android, although on all platforms
-  /// it is the default state before anything has been intitialized.
-  detached,
 }
 
 /// The possible responses to a request to exit the application.

lib/web_ui/lib/platform_dispatcher.dart

@@ -245,11 +245,11 @@ class FrameTiming {
 }
 
 enum AppLifecycleState {
+  detached,
   resumed,
   inactive,
   hidden,
   paused,
-  detached,
 }
 
 enum AppExitResponse {

shell/platform/common/application_lifecycle.h

@@ -11,49 +11,48 @@ namespace flutter {
 /// must be kept up to date with changes in the framework's AppLifecycleState
 /// enum. It is passed to the embedder's |SetLifecycleState| function.
 ///
-/// |SetLifecycleState| will validate that the state transition is a valid state
-/// transition, and will assert if it is not. States not supported on a platform
-/// will be emitted when transitioning between states which are supported, so
-/// that all implementations share the same allowed state machine. Here is the
-/// allowed state machine:
-///
-///             +-----------+                               +-----------+
-///             | detached  |------------------------------>|  resumed  |
-///             +-----------+                               +-----------+
-///                  ^                                              ^
-///                  |                                              |
-///                  |                                              v
-///             +-----------+        +--------------+       +-----------+
-///             | paused    |<------>|    hidden    |<----->|  inactive |
-///             +-----------+        +--------------+       +-----------+
-///
-/// The states and their meanings are as follows:
-///
-/// detached: The initial state of the state machine. On Android and iOS,
-///           also the final state of the state machine when all views are
-///           detached. Other platforms do not enter this state again after
-///           initially leaving it.
-///
-/// resumed: The nominal "running" state of the application. The
-///          application is visible, has input focus, and is running.
-///
-/// inactive: At least one view of the application is visible, but none
-///           have input focus. The application is otherwise running
-///           normally.
-///
-/// hidden: All views of an application are hidden, either because the
-///         application is being stopped (on iOS and Android), or because
-///         it is being minimized or on a desktop that is no longer visible
-///         (on desktop), or on a tab that is no longer visible (on web).
-///
-/// paused: The application is not running, and can be detached or started
-///         again at any time. This state is typically only entered into on
-///         iOS and Android.
+/// States not supported on a platform will be synthesized by the framework when
+/// transitioning between states which are supported, so that all
+/// implementations share the same state machine.
+///
+/// Here is the state machine:
+///
+///     +-----------+                               +-----------+
+///     | detached  |------------------------------>|  resumed  |
+///     +-----------+                               +-----------+
+///          ^                                              ^
+///          |                                              |
+///          |                                              v
+///     +-----------+        +--------------+       +-----------+
+///     | paused    |<------>|    hidden    |<----->|  inactive |
+///     +-----------+        +--------------+       +-----------+
 typedef enum {
+  /// Corresponds to AppLifecycleState.detached: The initial state of the state
+  /// machine. On Android and iOS, also the final state of the state machine
+  /// when all views are detached. Other platforms do not enter this state again
+  /// after initially leaving it.
   kAppLifecycleStateDetached = 0x0,
+
+  /// Corresponds to AppLifecycleState.resumed: The nominal "running" state of
+  /// the
+  /// application. The application is visible, has input focus, and is running.
   kAppLifecycleStateResumed = 0x1,
+
+  /// Corresponds to AppLifecycleState.inactive: At least one view of the
+  /// application is visible, but none have input focus. The application is
+  /// otherwise running normally.
   kAppLifecycleStateInactive = 0x2,
+
+  /// Corresponds to AppLifecycleState.hidden: All views of an application are
+  /// hidden, either because the application is being stopped (on iOS and
+  /// Android), or because it is being minimized or on a desktop that is no
+  /// longer visible (on desktop), or on a tab that is no longer visible (on
+  /// web).
   kAppLifecycleStateHidden = 0x3,
+
+  /// Corresponds to AppLifecycleState.paused: The application is not running,
+  /// and can be detached or started again at any time. This state is typically
+  /// only entered into on iOS and Android.
   kAppLifecycleStatePaused = 0x4,
 } AppLifecycleState;
 

shell/platform/darwin/macos/framework/Headers/FlutterAppLifecycleDelegate.h

@@ -15,7 +15,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 #pragma mark -
 /**
- * Protocol for listener of events from the NSApplication, typically a
+ * Protocol for listener of lifecycle events from the NSApplication, typically a
  * FlutterPlugin.
  */
 @protocol FlutterAppLifecycleDelegate <NSObject>
@@ -96,21 +96,28 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  * Called when the |FlutterAppDelegate| gets the applicationWillTerminate
  * notification.
+ *
+ * Applications should not rely on always receiving all possible notifications.
+ *
+ * For example, if the application is killed with a task manager, a kill signal,
+ * the user pulls the power from the device, or there is a rapid unscheduled
+ * disassembly of the device, no notification will be sent before the
+ * application is suddenly terminated, and this notification may be skipped.
  */
 - (void)handleWillTerminate:(NSNotification*)notification;
 @end
 
 #pragma mark -
 
 /**
- * Propagates `NSAppDelegate` callbacks to registered plugins.
+ * Propagates `NSAppDelegate` callbacks to registered delegates.
  */
 FLUTTER_DARWIN_EXPORT
 @interface FlutterAppLifecycleRegistrar : NSObject <FlutterAppLifecycleDelegate>
 
 /**
- * Registers `delegate` to receive life cycle callbacks via this FlutterAppLifecycleDelegate
- * as long as it is alive.
+ * Registers `delegate` to receive lifecycle callbacks via this
+ * FlutterAppLifecycleDelegate as long as it is alive.
  *
  * `delegate` will only be referenced weakly.
  */
@@ -119,6 +126,8 @@ FLUTTER_DARWIN_EXPORT
 /**
  * Unregisters `delegate` so that it will no longer receive life cycle callbacks
  * via this FlutterAppLifecycleDelegate.
+ *
+ * `delegate` will only be referenced weakly.
  */
 - (void)removeDelegate:(NSObject<FlutterAppLifecycleDelegate>*)delegate;
 @end

shell/platform/darwin/macos/framework/Source/FlutterAppLifecycleDelegate.mm

@@ -40,9 +40,10 @@ - (instancetype)init {
 // selector.
 #ifdef OBSERVE_NOTIFICATION
 #error OBSERVE_NOTIFICATION ALREADY DEFINED!
-#endif
+#else
 #define OBSERVE_NOTIFICATION(SELECTOR) \
   [self addObserverFor:NSApplication##SELECTOR##Notification selector:@selector(handle##SELECTOR:)]
+#endif
 
     OBSERVE_NOTIFICATION(WillFinishLaunching);
     OBSERVE_NOTIFICATION(DidFinishLaunching);
@@ -104,8 +105,9 @@ - (void)removeDelegate:(NSObject<FlutterAppLifecycleDelegate>*)delegate {
   }
 }
 
-// This isn't done via performSelector because that can cause leaks due
-// to the selector not being known.
+// This isn't done via performSelector because that can cause leaks due to the
+// selector not being known. Using a macro to avoid mismatch errors between the
+// notification and the selector.
 #ifdef DISTRIBUTE_NOTIFICATION
 #error DISTRIBUTE_NOTIFICATION ALREADY DEFINED!
 #else