SurfaceControlViewHost: Improve documentation

Capturing the answers to some questions I received today in-to
source-code comments.

Bug: 153756455
Test: Comments only
Change-Id: I208ca0370267803bf546d654f5a8d4e0c25b6f11

1 files changed, 16 insertions, 3 deletions

diff --git a/core/java/android/view/SurfaceView.java b/core/java/android/view/SurfaceView.java
index b677ccd9a618..9880ea096cf2 100644
--- a/core/java/android/view/SurfaceView.java
+++ b/core/java/android/view/SurfaceView.java
@@ -1650,11 +1650,24 @@ public class SurfaceView extends View implements ViewRootImpl.SurfaceChangedCall
 
     /**
      * Display the view-hierarchy embedded within a {@link SurfaceControlViewHost.SurfacePackage}
-     * within this SurfaceView. If this SurfaceView is above it's host Surface (see
+     * within this SurfaceView.
+     *
+     * This can be called independently of the SurfaceView lifetime callbacks. SurfaceView
+     * will internally manage reparenting the package to our Surface as it is created
+     * and destroyed.
+     *
+     * If this SurfaceView is above its host Surface (see
      * {@link #setZOrderOnTop} then the embedded Surface hierarchy will be able to receive
-     * input. This will take ownership of the SurfaceControl contained inside the SurfacePackage
+     * input.
+     *
+     * This will take ownership of the SurfaceControl contained inside the SurfacePackage
      * and free the caller of the obligation to call
-     * {@link SurfaceControlViewHost.SurfacePackage#release}.
+     * {@link SurfaceControlViewHost.SurfacePackage#release}. However, note that
+     * {@link SurfaceControlViewHost.SurfacePackage#release} and
+     * {@link SurfaceControlViewHost#release} are not the same. While the ownership
+     * of this particular {@link SurfaceControlViewHost.SurfacePackage} will be taken by the
+     * SurfaceView the underlying {@link SurfaceControlViewHost} remains managed by it's original
+     * remote-owner.
      *
      * @param p The SurfacePackage to embed.
      */