From c0ffeb262c4164086f92a85870d4f6223d1e3390 Mon Sep 17 00:00:00 2001
From: tonihei <tonihei@google.com>
Date: Mon, 15 Nov 2021 13:16:47 +0000
Subject: [PATCH] Add additional documentation regarding resource acquisition.

The main point of the IDLE state is that the player is not holding
resources. Clarify this in the documentation of STATE_IDLE, prepare and
stop.

PiperOrigin-RevId: 409950785
---
 .../java/androidx/media3/common/Player.java   | 21 +++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/libraries/common/src/main/java/androidx/media3/common/Player.java b/libraries/common/src/main/java/androidx/media3/common/Player.java
index 999f4258d7..87582bc1fe 100644
--- a/libraries/common/src/main/java/androidx/media3/common/Player.java
+++ b/libraries/common/src/main/java/androidx/media3/common/Player.java
@@ -1091,7 +1091,10 @@ public interface Player {
   @Target({FIELD, METHOD, PARAMETER, LOCAL_VARIABLE, TYPE_USE})
   @IntDef({STATE_IDLE, STATE_BUFFERING, STATE_READY, STATE_ENDED})
   @interface State {}
-  /** The player is idle, and must be {@link #prepare() prepared} before it will play the media. */
+  /**
+   * The player is idle, meaning it holds only limited resources. The player must be {@link
+   * #prepare() prepared} before it will play the media.
+   */
   int STATE_IDLE = 1;
   /**
    * The player is not able to immediately play the media, but is doing work toward being able to do
@@ -1674,7 +1677,12 @@ public interface Player {
    */
   Commands getAvailableCommands();
 
-  /** Prepares the player. */
+  /**
+   * Prepares the player.
+   *
+   * <p>This will move the player out of {@link #STATE_IDLE idle state} and the player will start
+   * loading media and acquire resources needed for playback.
+   */
   void prepare();
 
   /**
@@ -2014,12 +2022,13 @@ public interface Player {
   PlaybackParameters getPlaybackParameters();
 
   /**
-   * Stops playback without resetting the player. Use {@link #pause()} rather than this method if
+   * Stops playback without resetting the playlist. Use {@link #pause()} rather than this method if
    * the intention is to pause playback.
    *
-   * <p>Calling this method will cause the playback state to transition to {@link #STATE_IDLE}. The
-   * player instance can still be used, and {@link #release()} must still be called on the player if
-   * it's no longer required.
+   * <p>Calling this method will cause the playback state to transition to {@link #STATE_IDLE} and
+   * the player will release the loaded media and resources required for playback. The player
+   * instance can still be used by calling {@link #prepare()} again, and {@link #release()} must
+   * still be called on the player if it's no longer required.
    *
    * <p>Calling this method does not clear the playlist, reset the playback position or the playback
    * error.