Merge "PiP: API - explain isStashed in more detail." into sc-dev

core/java/android/app/PictureInPictureUiState.java

@@ -42,7 +42,20 @@ public final class PictureInPictureUiState implements Parcelable {
     }
 
     /**
-     * Returns whether Picture-in-Picture is stashed or not.
+     * Returns whether Picture-in-Picture is stashed or not. A stashed PiP means it is only
+     * partially visible to the user, with some parts of it being off-screen. This is usually
+     * an UI state that is triggered by the user, such as flinging the PiP to the edge or letting go
+     * of PiP while dragging partially off-screen.
+     *
+     * Developers can use this in conjunction with
+     * {@link Activity#onPictureInPictureUiStateChanged(PictureInPictureUiState)} to get a signal
+     * when the PiP stash state has changed. For example, if the state changed from {@code false} to
+     * {@code true}, developers can choose to temporarily pause video playback if PiP is of video
+     * content. Vice versa, if changing from {@code true} to {@code false} and video content is
+     * paused, developers can resumevideo playback.
+     *
+     * @see <a href="http://developer.android.com/about/versions/12/features/pip-improvements">
+     *     Picture in Picture (PiP) improvements</a>
      */
     public boolean isStashed() {
         return mIsStashed;