From e5bf5b2f50471db945e258a97edef270190fb56b Mon Sep 17 00:00:00 2001
From: Xiao Yu <xiao@xster.net>
Date: Wed, 11 Mar 2020 18:27:12 -0700
Subject: [PATCH 1/3] make a JavaDoc pass

---
 .../io/flutter/app/FlutterActivity.java       |  8 ++-
 .../io/flutter/app/FlutterApplication.java    |  3 +
 .../io/flutter/app/FlutterPluginRegistry.java |  2 +
 .../embedding/android/FlutterActivity.java    | 56 +++++++++++--------
 .../embedding/engine/FlutterEngine.java       |  3 +-
 .../embedding/engine/dart/DartExecutor.java   |  3 +-
 .../flutter/plugin/common/PluginRegistry.java |  3 +
 .../android/io/flutter/view/FlutterMain.java  |  6 +-
 .../android/io/flutter/view/FlutterView.java  |  6 +-
 9 files changed, 60 insertions(+), 30 deletions(-)

diff --git a/shell/platform/android/io/flutter/app/FlutterActivity.java b/shell/platform/android/io/flutter/app/FlutterActivity.java
index 6f8c13f46218b..da28c95fcb5aa 100644
--- a/shell/platform/android/io/flutter/app/FlutterActivity.java
+++ b/shell/platform/android/io/flutter/app/FlutterActivity.java
@@ -15,7 +15,13 @@
 import io.flutter.view.FlutterNativeView;
 import io.flutter.view.FlutterView;
 
-/** Base class for activities that use Flutter. */
+/**
+ * Deprecated base class for activities that use Flutter.
+ * <p>
+ * Deprecation: {@link io.flutter.embedding.android.FlutterActivity} is the new API that now
+ * replaces this class. See https://flutter.dev/go/android-project-migration for more migration
+ * details.
+ */
 public class FlutterActivity extends Activity
     implements FlutterView.Provider, PluginRegistry, ViewFactory {
   private static final String TAG = "FlutterActivity";
diff --git a/shell/platform/android/io/flutter/app/FlutterApplication.java b/shell/platform/android/io/flutter/app/FlutterApplication.java
index 1a5716d3c6d5b..bfdc6426d868a 100644
--- a/shell/platform/android/io/flutter/app/FlutterApplication.java
+++ b/shell/platform/android/io/flutter/app/FlutterApplication.java
@@ -12,6 +12,9 @@
 /**
  * Flutter implementation of {@link android.app.Application}, managing application-level global
  * initializations.
+ *
+ * Using this {@link android.app.Application} is not required when using APIs in the
+ * package {@code io.flutter.embedding.android} since they self-initialize on first use.
  */
 public class FlutterApplication extends Application {
   @Override
diff --git a/shell/platform/android/io/flutter/app/FlutterPluginRegistry.java b/shell/platform/android/io/flutter/app/FlutterPluginRegistry.java
index 54d9c801f4f80..b1979694cffdf 100644
--- a/shell/platform/android/io/flutter/app/FlutterPluginRegistry.java
+++ b/shell/platform/android/io/flutter/app/FlutterPluginRegistry.java
@@ -21,6 +21,8 @@
 import java.util.List;
 import java.util.Map;
 
+/// This class is now deprecated. See https://flutter.dev/go/android-project-migration for
+/// migration instructions.
 public class FlutterPluginRegistry
     implements PluginRegistry,
         PluginRegistry.RequestPermissionsResultListener,
diff --git a/shell/platform/android/io/flutter/embedding/android/FlutterActivity.java b/shell/platform/android/io/flutter/embedding/android/FlutterActivity.java
index fa74bc53fd7d5..0a070dc935ceb 100644
--- a/shell/platform/android/io/flutter/embedding/android/FlutterActivity.java
+++ b/shell/platform/android/io/flutter/embedding/android/FlutterActivity.java
@@ -51,11 +51,27 @@
  * <p>{@code FlutterActivity} is the simplest and most direct way to integrate Flutter within an
  * Android app.
  *
+ * <p><strong>FlutterActivity responsibilities</strong>
+ *
+ * <p>{@code FlutterActivity} maintains the following responsibilities:
+ *
+ * <ul>
+ *   <li>Displays an Android launch screen.
+ *   <li>Displays a Flutter splash screen.
+ *   <li>Configures the status bar appearance.
+ *   <li>Chooses the Dart execution app bundle path and entrypoint.
+ *   <li>Chooses Flutter's initial route.
+ *   <li>Renders {@code Activity} transparently, if desired.
+ *   <li>Offers hooks for subclasses to provide and configure a {@link FlutterEngine}.
+ * </ul>
+ *
  * <p><strong>Dart entrypoint, initial route, and app bundle path</strong>
  *
  * <p>The Dart entrypoint executed within this {@code Activity} is "main()" by default. To change
  * the entrypoint that a {@code FlutterActivity} executes, subclass {@code FlutterActivity} and
- * override {@link #getDartEntrypointFunctionName()}.
+ * override {@link #getDartEntrypointFunctionName()}. For non-main Dart entrypoints to not be
+ * tree-shaken away, you need to annotate those functions with {@code @pragma('vm:entry-point')}
+ * in Dart.
  *
  * <p>The Flutter route that is initially loaded within this {@code Activity} is "/". The initial
  * route may be specified explicitly by passing the name of the route as a {@code String} in {@link
@@ -73,11 +89,8 @@
  *   <li>{@link #getInitialRoute()}
  * </ul>
  *
- * <p>The Dart entrypoint and app bundle path are not supported as {@code Intent} parameters due to
- * security concerns. If such configurations were exposed via {@code Intent}, then a {@code
- * FlutterActivity} that is {@code exported} from your Android app would allow other apps to invoke
- * arbitrary Dart entrypoints in your app by specifying different Dart entrypoints for your {@code
- * FlutterActivity}. Therefore, these configurations are not available via {@code Intent}.
+ * <p>The Dart entrypoint and app bundle path are not supported as {@code Intent} parameters since
+ * your Dart library entrypoints are your private APIs and Intents are invocable by other processes.
  *
  * <p><strong>Using a cached FlutterEngine</strong>
  *
@@ -85,8 +98,10 @@
  * new one. Use {@link #withCachedEngine(String)} to build a {@code FlutterActivity} {@code Intent}
  * that is configured to use an existing, cached {@link FlutterEngine}. {@link
  * io.flutter.embedding.engine.FlutterEngineCache} is the cache that is used to obtain a given
- * cached {@link FlutterEngine}. An {@code IllegalStateException} will be thrown if a cached engine
- * is requested but does not exist in the cache.
+ * cached {@link FlutterEngine}. You must create and put a {@link FlutterEngine} into the
+ * {@link io.flutter.embedding.engine.FlutterEngineCache} yourself before using the
+ * {@link #withCachedEngine(String)} builder. An {@code IllegalStateException} will be thrown if a
+ * cached engine is requested but does not exist in the cache.
  *
  * <p>When using a cached {@link FlutterEngine}, that {@link FlutterEngine} should already be
  * executing Dart code, which means that the Dart entrypoint and initial route have already been
@@ -104,6 +119,9 @@
  *       pre-warming a {@link FlutterEngine} would have no impact in this situation.
  *   <li>When you are unsure when/if you will need to display a Flutter experience.
  * </ul>
+ * <p>
+ * See https://flutter.dev/docs/development/add-to-app/performance for additional performance
+ * explorations on engine loading.
  *
  * <p>The following illustrates how to pre-warm and cache a {@link FlutterEngine}:
  *
@@ -126,20 +144,6 @@
  * FlutterView}. Using a {@link FlutterView} requires forwarding some calls from an {@code
  * Activity}, as well as forwarding lifecycle calls from an {@code Activity} or a {@code Fragment}.
  *
- * <p><strong>FlutterActivity responsibilities</strong>
- *
- * <p>{@code FlutterActivity} maintains the following responsibilities:
- *
- * <ul>
- *   <li>Displays an Android launch screen.
- *   <li>Displays a Flutter splash screen.
- *   <li>Configures the status bar appearance.
- *   <li>Chooses the Dart execution app bundle path and entrypoint.
- *   <li>Chooses Flutter's initial route.
- *   <li>Renders {@code Activity} transparently, if desired.
- *   <li>Offers hooks for subclasses to provide and configure a {@link FlutterEngine}.
- * </ul>
- *
  * <p><strong>Launch Screen and Splash Screen</strong>
  *
  * <p>{@code FlutterActivity} supports the display of an Android "launch screen" as well as a
@@ -196,8 +200,12 @@ public class FlutterActivity extends Activity
   private static final String TAG = "FlutterActivity";
 
   /**
-   * Creates an {@link Intent} that launches a {@code FlutterActivity}, which executes a {@code
-   * main()} Dart entrypoint, and displays the "/" route as Flutter's initial route.
+   * Creates an {@link Intent} that launches a {@code FlutterActivity}, which creates a
+   * {@link FlutterEngine} that executes a {@code main()} Dart entrypoint, and displays the "/"
+   * route as Flutter's initial route.
+   * <p>
+   * Consider using the {@link #withCachedEngine(String)} {@link Intent} builder to control when
+   * the {@link FlutterEngine} should be created in your application.
    */
   @NonNull
   public static Intent createDefaultIntent(@NonNull Context launchContext) {
diff --git a/shell/platform/android/io/flutter/embedding/engine/FlutterEngine.java b/shell/platform/android/io/flutter/embedding/engine/FlutterEngine.java
index 0c094e0bb1e7f..b817618c72108 100644
--- a/shell/platform/android/io/flutter/embedding/engine/FlutterEngine.java
+++ b/shell/platform/android/io/flutter/embedding/engine/FlutterEngine.java
@@ -44,7 +44,8 @@
  * interaction.
  *
  * <p>Multiple {@code FlutterEngine}s may exist, execute Dart code, and render UIs within a single
- * Android app.
+ * Android app. Flutter at this point makes no guarantees on the performance of running multiple
+ * engines. Use at your own risk. See https://github.com/flutter/flutter/issues/37644 for details.
  *
  * <p>To start running Dart and/or Flutter within this {@code FlutterEngine}, get a reference to
  * this engine's {@link DartExecutor} and then use {@link
diff --git a/shell/platform/android/io/flutter/embedding/engine/dart/DartExecutor.java b/shell/platform/android/io/flutter/embedding/engine/dart/DartExecutor.java
index 4ae449a3d1f69..edf9ef9adbdd9 100644
--- a/shell/platform/android/io/flutter/embedding/engine/dart/DartExecutor.java
+++ b/shell/platform/android/io/flutter/embedding/engine/dart/DartExecutor.java
@@ -26,8 +26,7 @@
  *
  * <p>To specify a Dart callback to execute, use a {@link DartCallback}. A given Dart callback must
  * be registered with the Dart VM to be invoked by a {@link DartExecutor}. To execute the callback,
- * pass the {@link DartCallback} to {@link #executeDartCallback(DartCallback)}. TODO(mattcarroll):
- * add a reference to docs about background/plugin execution
+ * pass the {@link DartCallback} to {@link #executeDartCallback(DartCallback)}.
  *
  * <p>Once started, a {@link DartExecutor} cannot be stopped. The associated Dart code will execute
  * until it completes, or until the {@link io.flutter.embedding.engine.FlutterEngine} that owns this
diff --git a/shell/platform/android/io/flutter/plugin/common/PluginRegistry.java b/shell/platform/android/io/flutter/plugin/common/PluginRegistry.java
index f0082bc667488..b47bdd1054922 100644
--- a/shell/platform/android/io/flutter/plugin/common/PluginRegistry.java
+++ b/shell/platform/android/io/flutter/plugin/common/PluginRegistry.java
@@ -24,6 +24,9 @@
  * registrant class is, again by default, called from the application's main {@link Activity}, which
  * defaults to an instance of {@link io.flutter.app.FlutterActivity}, itself a {@link
  * PluginRegistry}.
+ *
+ * This class is now deprecated. See https://flutter.dev/go/android-project-migration for migration
+ * details.
  */
 public interface PluginRegistry {
   /**
diff --git a/shell/platform/android/io/flutter/view/FlutterMain.java b/shell/platform/android/io/flutter/view/FlutterMain.java
index 34a9a2582c1cc..d6693a9de309e 100644
--- a/shell/platform/android/io/flutter/view/FlutterMain.java
+++ b/shell/platform/android/io/flutter/view/FlutterMain.java
@@ -11,7 +11,11 @@
 import android.support.annotation.VisibleForTesting;
 import io.flutter.embedding.engine.loader.FlutterLoader;
 
-/** A class to intialize the Flutter engine. */
+/**
+ * A legacy class to initialize the Flutter engine.
+ * <p>
+ * Replaced by {@link io.flutter.embedding.engine.loader.FlutterLoader}.
+ */
 public class FlutterMain {
 
   public static class Settings {
diff --git a/shell/platform/android/io/flutter/view/FlutterView.java b/shell/platform/android/io/flutter/view/FlutterView.java
index 55977a0f42b02..a2da543427eb7 100644
--- a/shell/platform/android/io/flutter/view/FlutterView.java
+++ b/shell/platform/android/io/flutter/view/FlutterView.java
@@ -60,7 +60,11 @@
 import java.util.Locale;
 import java.util.concurrent.atomic.AtomicLong;
 
-/** An Android view containing a Flutter app. */
+/**
+ * Deprecated Android view containing a Flutter app.
+ * Deprecation: {@link io.flutter.embedding.android.FlutterView} is the new API that now
+ * replaces this class. See https://flutter.dev/go/android-project-migration for more migration
+ * details.*/
 public class FlutterView extends SurfaceView implements BinaryMessenger, TextureRegistry {
   /**
    * Interface for those objects that maintain and expose a reference to a {@code FlutterView} (such

From 321f73ade26bb47ae21592e52792559e0f39b57f Mon Sep 17 00:00:00 2001
From: Xiao Yu <xiao@xster.net>
Date: Wed, 11 Mar 2020 18:29:30 -0700
Subject: [PATCH 2/3] missed a paragraph

---
 shell/platform/android/io/flutter/view/FlutterView.java | 1 +
 1 file changed, 1 insertion(+)

diff --git a/shell/platform/android/io/flutter/view/FlutterView.java b/shell/platform/android/io/flutter/view/FlutterView.java
index a2da543427eb7..3e11237f48049 100644
--- a/shell/platform/android/io/flutter/view/FlutterView.java
+++ b/shell/platform/android/io/flutter/view/FlutterView.java
@@ -62,6 +62,7 @@
 
 /**
  * Deprecated Android view containing a Flutter app.
+ * <p>
  * Deprecation: {@link io.flutter.embedding.android.FlutterView} is the new API that now
  * replaces this class. See https://flutter.dev/go/android-project-migration for more migration
  * details.*/

From c31ca996b5581da914be6a1e5af045268008101e Mon Sep 17 00:00:00 2001
From: Xiao Yu <xiao@xster.net>
Date: Thu, 12 Mar 2020 01:09:11 -0700
Subject: [PATCH 3/3] autoformat

---
 .../io/flutter/app/FlutterActivity.java       |  4 +--
 .../io/flutter/app/FlutterApplication.java    |  4 +--
 .../embedding/android/FlutterActivity.java    | 26 +++++++++----------
 .../flutter/plugin/common/PluginRegistry.java |  4 +--
 .../android/io/flutter/view/FlutterMain.java  |  4 +--
 .../android/io/flutter/view/FlutterView.java  |  8 +++---
 6 files changed, 25 insertions(+), 25 deletions(-)

diff --git a/shell/platform/android/io/flutter/app/FlutterActivity.java b/shell/platform/android/io/flutter/app/FlutterActivity.java
index da28c95fcb5aa..816b0c13e3684 100644
--- a/shell/platform/android/io/flutter/app/FlutterActivity.java
+++ b/shell/platform/android/io/flutter/app/FlutterActivity.java
@@ -17,8 +17,8 @@
 
 /**
  * Deprecated base class for activities that use Flutter.
- * <p>
- * Deprecation: {@link io.flutter.embedding.android.FlutterActivity} is the new API that now
+ *
+ * <p>Deprecation: {@link io.flutter.embedding.android.FlutterActivity} is the new API that now
  * replaces this class. See https://flutter.dev/go/android-project-migration for more migration
  * details.
  */
diff --git a/shell/platform/android/io/flutter/app/FlutterApplication.java b/shell/platform/android/io/flutter/app/FlutterApplication.java
index bfdc6426d868a..1dc11e868c8d3 100644
--- a/shell/platform/android/io/flutter/app/FlutterApplication.java
+++ b/shell/platform/android/io/flutter/app/FlutterApplication.java
@@ -13,8 +13,8 @@
  * Flutter implementation of {@link android.app.Application}, managing application-level global
  * initializations.
  *
- * Using this {@link android.app.Application} is not required when using APIs in the
- * package {@code io.flutter.embedding.android} since they self-initialize on first use.
+ * <p>Using this {@link android.app.Application} is not required when using APIs in the package
+ * {@code io.flutter.embedding.android} since they self-initialize on first use.
  */
 public class FlutterApplication extends Application {
   @Override
diff --git a/shell/platform/android/io/flutter/embedding/android/FlutterActivity.java b/shell/platform/android/io/flutter/embedding/android/FlutterActivity.java
index 0a070dc935ceb..cb88fa4430e25 100644
--- a/shell/platform/android/io/flutter/embedding/android/FlutterActivity.java
+++ b/shell/platform/android/io/flutter/embedding/android/FlutterActivity.java
@@ -70,8 +70,8 @@
  * <p>The Dart entrypoint executed within this {@code Activity} is "main()" by default. To change
  * the entrypoint that a {@code FlutterActivity} executes, subclass {@code FlutterActivity} and
  * override {@link #getDartEntrypointFunctionName()}. For non-main Dart entrypoints to not be
- * tree-shaken away, you need to annotate those functions with {@code @pragma('vm:entry-point')}
- * in Dart.
+ * tree-shaken away, you need to annotate those functions with {@code @pragma('vm:entry-point')} in
+ * Dart.
  *
  * <p>The Flutter route that is initially loaded within this {@code Activity} is "/". The initial
  * route may be specified explicitly by passing the name of the route as a {@code String} in {@link
@@ -98,10 +98,10 @@
  * new one. Use {@link #withCachedEngine(String)} to build a {@code FlutterActivity} {@code Intent}
  * that is configured to use an existing, cached {@link FlutterEngine}. {@link
  * io.flutter.embedding.engine.FlutterEngineCache} is the cache that is used to obtain a given
- * cached {@link FlutterEngine}. You must create and put a {@link FlutterEngine} into the
- * {@link io.flutter.embedding.engine.FlutterEngineCache} yourself before using the
- * {@link #withCachedEngine(String)} builder. An {@code IllegalStateException} will be thrown if a
- * cached engine is requested but does not exist in the cache.
+ * cached {@link FlutterEngine}. You must create and put a {@link FlutterEngine} into the {@link
+ * io.flutter.embedding.engine.FlutterEngineCache} yourself before using the {@link
+ * #withCachedEngine(String)} builder. An {@code IllegalStateException} will be thrown if a cached
+ * engine is requested but does not exist in the cache.
  *
  * <p>When using a cached {@link FlutterEngine}, that {@link FlutterEngine} should already be
  * executing Dart code, which means that the Dart entrypoint and initial route have already been
@@ -119,8 +119,8 @@
  *       pre-warming a {@link FlutterEngine} would have no impact in this situation.
  *   <li>When you are unsure when/if you will need to display a Flutter experience.
  * </ul>
- * <p>
- * See https://flutter.dev/docs/development/add-to-app/performance for additional performance
+ *
+ * <p>See https://flutter.dev/docs/development/add-to-app/performance for additional performance
  * explorations on engine loading.
  *
  * <p>The following illustrates how to pre-warm and cache a {@link FlutterEngine}:
@@ -200,11 +200,11 @@ public class FlutterActivity extends Activity
   private static final String TAG = "FlutterActivity";
 
   /**
-   * Creates an {@link Intent} that launches a {@code FlutterActivity}, which creates a
-   * {@link FlutterEngine} that executes a {@code main()} Dart entrypoint, and displays the "/"
-   * route as Flutter's initial route.
-   * <p>
-   * Consider using the {@link #withCachedEngine(String)} {@link Intent} builder to control when
+   * Creates an {@link Intent} that launches a {@code FlutterActivity}, which creates a {@link
+   * FlutterEngine} that executes a {@code main()} Dart entrypoint, and displays the "/" route as
+   * Flutter's initial route.
+   *
+   * <p>Consider using the {@link #withCachedEngine(String)} {@link Intent} builder to control when
    * the {@link FlutterEngine} should be created in your application.
    */
   @NonNull
diff --git a/shell/platform/android/io/flutter/plugin/common/PluginRegistry.java b/shell/platform/android/io/flutter/plugin/common/PluginRegistry.java
index b47bdd1054922..abd06c30f2f49 100644
--- a/shell/platform/android/io/flutter/plugin/common/PluginRegistry.java
+++ b/shell/platform/android/io/flutter/plugin/common/PluginRegistry.java
@@ -25,8 +25,8 @@
  * defaults to an instance of {@link io.flutter.app.FlutterActivity}, itself a {@link
  * PluginRegistry}.
  *
- * This class is now deprecated. See https://flutter.dev/go/android-project-migration for migration
- * details.
+ * <p>This class is now deprecated. See https://flutter.dev/go/android-project-migration for
+ * migration details.
  */
 public interface PluginRegistry {
   /**
diff --git a/shell/platform/android/io/flutter/view/FlutterMain.java b/shell/platform/android/io/flutter/view/FlutterMain.java
index d6693a9de309e..bbcea46b3775e 100644
--- a/shell/platform/android/io/flutter/view/FlutterMain.java
+++ b/shell/platform/android/io/flutter/view/FlutterMain.java
@@ -13,8 +13,8 @@
 
 /**
  * A legacy class to initialize the Flutter engine.
- * <p>
- * Replaced by {@link io.flutter.embedding.engine.loader.FlutterLoader}.
+ *
+ * <p>Replaced by {@link io.flutter.embedding.engine.loader.FlutterLoader}.
  */
 public class FlutterMain {
 
diff --git a/shell/platform/android/io/flutter/view/FlutterView.java b/shell/platform/android/io/flutter/view/FlutterView.java
index 3e11237f48049..98066479053f0 100644
--- a/shell/platform/android/io/flutter/view/FlutterView.java
+++ b/shell/platform/android/io/flutter/view/FlutterView.java
@@ -62,10 +62,10 @@
 
 /**
  * Deprecated Android view containing a Flutter app.
- * <p>
- * Deprecation: {@link io.flutter.embedding.android.FlutterView} is the new API that now
- * replaces this class. See https://flutter.dev/go/android-project-migration for more migration
- * details.*/
+ *
+ * <p>Deprecation: {@link io.flutter.embedding.android.FlutterView} is the new API that now replaces
+ * this class. See https://flutter.dev/go/android-project-migration for more migration details.
+ */
 public class FlutterView extends SurfaceView implements BinaryMessenger, TextureRegistry {
   /**
    * Interface for those objects that maintain and expose a reference to a {@code FlutterView} (such