diff --git a/shell/platform/darwin/ios/framework/Headers/FlutterEngine.h b/shell/platform/darwin/ios/framework/Headers/FlutterEngine.h
index 51782ceca07..46980d609a0 100644
--- a/shell/platform/darwin/ios/framework/Headers/FlutterEngine.h
+++ b/shell/platform/darwin/ios/framework/Headers/FlutterEngine.h
@@ -36,6 +36,11 @@ extern NSString* const FlutterDefaultDartEntrypoint;
  * `FlutterViewController` instances to maintain state and/or asynchronous tasks
  * (such as downloading a large file).
  *
+ * A FlutterEngine can also be used to prewarm the Dart execution environment and reduce the
+ * latency of showing the Flutter screen when a `FlutterViewController` is created and presented.
+ * See http://flutter.dev/docs/development/add-to-app/performance for more details on loading
+ * performance.
+ *
  * Alternatively, you can simply create a new `FlutterViewController` with only a
  * `FlutterDartProject`. That `FlutterViewController` will internally manage its
  * own instance of a FlutterEngine, but will not guarantee survival of the engine
diff --git a/shell/platform/darwin/ios/framework/Headers/FlutterHeadlessDartRunner.h b/shell/platform/darwin/ios/framework/Headers/FlutterHeadlessDartRunner.h
index 24acbc08ad6..1994cfc81f9 100644
--- a/shell/platform/darwin/ios/framework/Headers/FlutterHeadlessDartRunner.h
+++ b/shell/platform/darwin/ios/framework/Headers/FlutterHeadlessDartRunner.h
@@ -22,7 +22,7 @@
 typedef void (^FlutterHeadlessDartRunnerCallback)(BOOL success);
 
 /**
- * The FlutterHeadlessDartRunner runs Flutter Dart code with a null rasterizer,
+ * The deprecated FlutterHeadlessDartRunner runs Flutter Dart code with a null rasterizer,
  * and no native drawing surface. It is appropriate for use in running Dart
  * code e.g. in the background from a plugin.
  *
diff --git a/shell/platform/darwin/ios/framework/Headers/FlutterViewController.h b/shell/platform/darwin/ios/framework/Headers/FlutterViewController.h
index 9753cdb68bc..77bf219f128 100644
--- a/shell/platform/darwin/ios/framework/Headers/FlutterViewController.h
+++ b/shell/platform/darwin/ios/framework/Headers/FlutterViewController.h
@@ -35,14 +35,17 @@ extern NSNotificationName const FlutterSemanticsUpdateNotification;
  * handled by `FlutterEngine`. Calls on this class to those members all proxy through to the
  * `FlutterEngine` attached FlutterViewController.
  *
- * A FlutterViewController can be initialized either with an already-running `FlutterEngine` via
- * the `initWithEngine:` initializer, or it can be initialized with a `FlutterDartProject` that
- * will be used to implicitly spin up a new `FlutterEngine`. Creating a `FlutterEngine before
- * showing a `FlutterViewController` can be used to pre-initialize the Dart VM and to prepare the
- * isolate in order to reduce the latency to the first rendered frame. Holding a `FlutterEngine`
- * independently of FlutterViewControllers can also be used to not to lose Dart-related state and
- * asynchronous tasks when navigating back and forth between a FlutterViewController and other
- * `UIViewController`s.
+ * A FlutterViewController can be initialized either with an already-running `FlutterEngine` via the
+ * `initWithEngine:` initializer, or it can be initialized with a `FlutterDartProject` that will be
+ * used to implicitly spin up a new `FlutterEngine`. Creating a `FlutterEngine before showing a
+ * FlutterViewController can be used to pre-initialize the Dart VM and to prepare the isolate in
+ * order to reduce the latency to the first rendered frame. See
+ * https://flutter.dev/docs/development/add-to-app/performance for more details on loading
+ * latency.
+ *
+ * Holding a `FlutterEngine` independently of FlutterViewControllers can also be used to not to lose
+ * Dart-related state and asynchronous tasks when navigating back and forth between a
+ * FlutterViewController and other `UIViewController`s.
  */
 FLUTTER_EXPORT
 @interface FlutterViewController : UIViewController <FlutterTextureRegistry, FlutterPluginRegistry>
@@ -64,6 +67,9 @@ FLUTTER_EXPORT
  * Initializes a new FlutterViewController and `FlutterEngine` with the specified
  * `FlutterDartProject`.
  *
+ * This will implicitly create a new `FlutterEngine` which is retrievable via the `engine` property
+ * after initialization.
+ *
  * @param project The `FlutterDartProject` to initialize the `FlutterEngine` with.
  * @param nibName The NIB name to initialize this UIViewController with.
  * @param nibBundle The NIB bundle.
@@ -174,7 +180,9 @@ FLUTTER_EXPORT
 @property(nonatomic, getter=isViewOpaque) BOOL viewOpaque;
 
 /**
- * The `FlutterEngine` instance for this view controller.
+ * The `FlutterEngine` instance for this view controller. This could be the engine this
+ * `FlutterViewController` is initialized with or a new `FlutterEngine` implicitly created if
+ * no engine was supplied during initialization.
  */
 @property(weak, nonatomic, readonly) FlutterEngine* engine;