More documentation changes

Author: GaryQian

shell/common/engine.h

@@ -269,7 +269,10 @@ class Engine final : public RuntimeDelegate,
     ///             `LoadDartDeferredLibrary`
     ///
     /// @param[in]  loading_unit_id  The unique id of the deferred library's
-    ///                              loading unit.
+    ///                              loading unit. This id is to be passed
+    ///                              back into LoadDartDeferredLibrary
+    ///                              in order to identify which deferred
+    ///                              library to load.
     ///
     virtual void RequestDartDeferredLibrary(intptr_t loading_unit_id) = 0;
   };
@@ -787,17 +790,19 @@ class Engine final : public RuntimeDelegate,
   ///             The Dart compiler may generate separate shared libraries
   ///             files called 'loading units' when libraries are imported
   ///             as deferred. Each of these shared libraries are identified
-  ///             by a unique loading unit id and can be dynamically loaded
-  ///             into the VM by dlopen-ing and resolving the data and
-  ///             instructions symbols.
+  ///             by a unique loading unit id. Callers should dlopen the
+  ///             shared library file and use dlsym to resolve the dart
+  ///             symbols. These symbols can then be passed to this method to
+  ///             be dynamically loaded into the VM.
   ///
   ///             This method is paired with a RequestDartDeferredLibrary
   ///             invocation that provides the embedder with the loading unit id
   ///             of the deferred library to load.
   ///
   ///
   /// @param[in]  loading_unit_id  The unique id of the deferred library's
-  ///                              loading unit.
+  ///                              loading unit, as passed in by
+  ///                              RequestDartDeferredLibrary.
   ///
   /// @param[in]  snapshot_data    Dart snapshot data of the loading unit's
   ///                              shared library.

shell/common/platform_view.h

@@ -238,6 +238,8 @@ class PlatformView {
         const uint8_t* snapshot_data,
         const uint8_t* snapshot_instructions) = 0;
 
+    // TODO(garyq): Implement a proper asset_resolver replacement instead of
+    // overwriting the entire asset manager.
     //--------------------------------------------------------------------------
     /// @brief      Sets the asset manager of the engine to asset_manager
     ///
@@ -608,7 +610,10 @@ class PlatformView {
   ///             `LoadDartDeferredLibrary`
   ///
   /// @param[in]  loading_unit_id  The unique id of the deferred library's
-  ///                              loading unit.
+  ///                              loading unit. This id is to be passed
+  ///                              back into LoadDartDeferredLibrary
+  ///                              in order to identify which deferred
+  ///                              library to load.
   ///
   virtual void RequestDartDeferredLibrary(intptr_t loading_unit_id);
 
@@ -620,17 +625,19 @@ class PlatformView {
   ///             The Dart compiler may generate separate shared libraries
   ///             files called 'loading units' when libraries are imported
   ///             as deferred. Each of these shared libraries are identified
-  ///             by a unique loading unit id and can be dynamically loaded
-  ///             into the VM by dlopen-ing and resolving the data and
-  ///             instructions symbols.
+  ///             by a unique loading unit id. Callers should dlopen the
+  ///             shared library file and use dlsym to resolve the dart
+  ///             symbols. These symbols can then be passed to this method to
+  ///             be dynamically loaded into the VM.
   ///
   ///             This method is paired with a RequestDartDeferredLibrary
   ///             invocation that provides the embedder with the loading unit id
   ///             of the deferred library to load.
   ///
   ///
   /// @param[in]  loading_unit_id  The unique id of the deferred library's
-  ///                              loading unit.
+  ///                              loading unit, as passed in by
+  ///                              RequestDartDeferredLibrary.
   ///
   /// @param[in]  snapshot_data    Dart snapshot data of the loading unit's
   ///                              shared library.

shell/platform/android/embedding_bundle/build.gradle

@@ -48,6 +48,10 @@ android {
     embedding "androidx.lifecycle:lifecycle-common:$lifecycle_version"
     embedding "androidx.lifecycle:lifecycle-common-java8:$lifecycle_version"
 
+    // This dependency is here to allow linking to Play core in tests, but
+    // is not used in a default Flutter app. This dependency should be manually
+    // added to the user's app gradle in order to opt into using split AOT
+    // dynamic features.
     embedding "com.google.android.play:core:1.8.0"
 
     // Testing