Make a pass through all the embedding javadocs

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";

shell/platform/android/io/flutter/app/FlutterApplication.java

@@ -12,6 +12,9 @@
 /**
  * Flutter implementation of {@link android.app.Application}, managing application-level global
  * initializations.
+ *
+ * <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

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,

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,20 +89,19 @@
  *   <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>
  *
  * <p>{@code FlutterActivity} can be used with a cached {@link FlutterEngine} instead of creating a
  * 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
@@ -105,6 +120,9 @@
  *   <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}:
  *
  * <pre>{@code
@@ -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) {

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

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

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}.
+ *
+ * <p>This class is now deprecated. See https://flutter.dev/go/android-project-migration for
+ * migration details.
  */
 public interface PluginRegistry {
   /**

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 {

shell/platform/android/io/flutter/view/FlutterView.java

@@ -60,7 +60,12 @@
 import java.util.Locale;
 import java.util.concurrent.atomic.AtomicLong;
 
-/** An Android view containing a Flutter app. */
+/**
+ * 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.
+ */
 public class FlutterView extends SurfaceView implements BinaryMessenger, TextureRegistry {
   /**
    * Interface for those objects that maintain and expose a reference to a {@code FlutterView} (such