Add documentation to #onPictureInPictureRequested

Explains how app developers might want to use the new API.

Bug: 148011369
Test: compiles
Change-Id: I87b20de69ea9a30c2cb338cf19db0bd0b971b78a

1 files changed, 7 insertions, 1 deletions

diff --git a/core/java/android/app/Activity.java b/core/java/android/app/Activity.java
index d952be5218a4..67c5d089938e 100644
--- a/core/java/android/app/Activity.java
+++ b/core/java/android/app/Activity.java
@@ -2839,7 +2839,13 @@ public class Activity extends ContextThemeWrapper
     }
 
     /**
-     * Called by the system when picture in picture mode should be entered if supported.
+     * This method is called by the system in various cases where picture in picture mode should be
+     * entered if supported.
+     *
+     * <p>It is up to the app developer to choose whether to call
+     * {@link #enterPictureInPictureMode(PictureInPictureParams)} at this time. For example, the
+     * system will call this method when the activity is being put into the background, so the app
+     * developer might want to switch an activity into PIP mode instead.</p>
      */
     public void onPictureInPictureRequested() {
         // Previous recommendation was for apps to enter picture-in-picture in onUserLeaveHint()