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

docs/listening-to-player-events.md

@@ -31,7 +31,8 @@ Changes in player state can be received by implementing
 `Player.Listener`. The player can be in one of four playback states:
 
 * `Player.STATE_IDLE`: This is the initial state, the state when the player is
-  stopped, and when playback failed.
+  stopped, and when playback failed. The player will hold only limited resources
+  in this state.
 * `Player.STATE_BUFFERING`: The player is not able to immediately play from its
   current position. This mostly happens because more data needs to be loaded.
 * `Player.STATE_READY`: The player is able to immediately play from its current

library/common/src/main/java/com/google/android/exoplayer2/Player.java

@@ -1087,7 +1087,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
@@ -1669,7 +1672,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();
 
   /**
@@ -2001,12 +2009,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
+   * <p>Calling this method will cause the playback state to transition to {@link #STATE_IDLE} and
-   * player instance can still be used, and {@link #release()} must still be called on the player if
+   * the player will release the loaded media and resources required for playback. The player
-   * it's no longer required.
+   * 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.