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, 0 deletions

diff --git a/core/java/android/view/SurfaceControlViewHost.java b/core/java/android/view/SurfaceControlViewHost.java
index 174165c5ba59..cfceb031539f 100644
--- a/core/java/android/view/SurfaceControlViewHost.java
+++ b/core/java/android/view/SurfaceControlViewHost.java
@@ -50,6 +50,22 @@ public class SurfaceControlViewHost {
      * elements. It's expected to get this object from
      * {@link SurfaceControlViewHost#getSurfacePackage} afterwards it can be embedded within
      * a SurfaceView by calling {@link SurfaceView#setChildSurfacePackage}.
+     *
+     * Note that each {@link SurfacePackage} must be released by calling
+     * {@link SurfacePackage#release}. However, if you use the recommended flow,
+     *  the framework will automatically handle the lifetime for you.
+     *
+     * 1. When sending the package to the remote process, return it from an AIDL method
+     * or manually use FLAG_WRITE_RETURN_VALUE in writeToParcel. This will automatically
+     * release the package in the local process.
+     * 2. In the remote process, consume the package using SurfaceView. This way the
+     * SurfaceView will take over the lifetime and call {@link SurfacePackage#release}
+     * for the user.
+     *
+     * One final note: The {@link SurfacePackage} lifetime is totally de-coupled
+     * from the lifetime of the underlying {@link SurfaceControlViewHost}. Regardless
+     * of the lifetime of the package the user should still call
+     * {@link SurfaceControlViewHost#release} when finished.
      */
     public static final class SurfacePackage implements Parcelable {
         private SurfaceControl mSurfaceControl;