From b8ca5b8951325ed89063b2e30e1c7fd3b78f5e97 Mon Sep 17 00:00:00 2001
From: ibaker <ibaker@google.com>
Date: Tue, 31 May 2022 10:09:10 +0000
Subject: [PATCH] Add `@deprecated` javadoc to all `@Deprecated` `@Override`
 methods

This ensures the 'use X instead' message is easily visible in the
generated HTML for the overriding method. Currently it's not, e.g.:
https://exoplayer.dev/doc/reference/com/google/android/exoplayer2/BasePlayer.html#getCurrentWindowIndex()

#minor-release

PiperOrigin-RevId: 452002224
---
 .../java/androidx/media3/cast/CastPlayer.java |  5 +
 .../androidx/media3/common/BasePlayer.java    | 42 +++++++++
 .../media3/common/ForwardingPlayer.java       | 92 ++++++++++++++++---
 .../datasource/cronet/CronetDataSource.java   |  6 +-
 .../media3/exoplayer/SimpleExoPlayer.java     | 37 ++++++++
 .../trackselection/DefaultTrackSelector.java  |  3 +
 .../media3/session/MediaController.java       | 47 ++++++++++
 .../androidx/media3/session/MockPlayer.java   | 47 ++++++++++
 .../media3/test/utils/StubExoPlayer.java      | 37 ++++++++
 .../media3/test/utils/StubPlayer.java         |  5 +
 10 files changed, 301 insertions(+), 20 deletions(-)

diff --git a/libraries/cast/src/main/java/androidx/media3/cast/CastPlayer.java b/libraries/cast/src/main/java/androidx/media3/cast/CastPlayer.java
index 3ab3878864..ad21e461e7 100644
--- a/libraries/cast/src/main/java/androidx/media3/cast/CastPlayer.java
+++ b/libraries/cast/src/main/java/androidx/media3/cast/CastPlayer.java
@@ -458,6 +458,11 @@ public final class CastPlayer extends BasePlayer {
     stop(/* reset= */ false);
   }
 
+  /**
+   * @deprecated Use {@link #stop()} and {@link #clearMediaItems()} (if {@code reset} is true) or
+   *     just {@link #stop()} (if {@code reset} is false). Any player error will be cleared when
+   *     {@link #prepare() re-preparing} the player.
+   */
   @Deprecated
   @Override
   public void stop(boolean reset) {
diff --git a/libraries/common/src/main/java/androidx/media3/common/BasePlayer.java b/libraries/common/src/main/java/androidx/media3/common/BasePlayer.java
index f45f131812..fc5a96c96e 100644
--- a/libraries/common/src/main/java/androidx/media3/common/BasePlayer.java
+++ b/libraries/common/src/main/java/androidx/media3/common/BasePlayer.java
@@ -143,12 +143,18 @@ public abstract class BasePlayer implements Player {
     seekToOffset(getSeekForwardIncrement());
   }
 
+  /**
+   * @deprecated Use {@link #hasPreviousMediaItem()} instead.
+   */
   @Deprecated
   @Override
   public final boolean hasPrevious() {
     return hasPreviousMediaItem();
   }
 
+  /**
+   * @deprecated Use {@link #hasPreviousMediaItem()} instead.
+   */
   @Deprecated
   @Override
   public final boolean hasPreviousWindow() {
@@ -160,12 +166,18 @@ public abstract class BasePlayer implements Player {
     return getPreviousMediaItemIndex() != C.INDEX_UNSET;
   }
 
+  /**
+   * @deprecated Use {@link #seekToPreviousMediaItem()} instead.
+   */
   @Deprecated
   @Override
   public final void previous() {
     seekToPreviousMediaItem();
   }
 
+  /**
+   * @deprecated Use {@link #seekToPreviousMediaItem()} instead.
+   */
   @Deprecated
   @Override
   public final void seekToPreviousWindow() {
@@ -198,12 +210,18 @@ public abstract class BasePlayer implements Player {
     }
   }
 
+  /**
+   * @deprecated Use {@link #hasNextMediaItem()} instead.
+   */
   @Deprecated
   @Override
   public final boolean hasNext() {
     return hasNextMediaItem();
   }
 
+  /**
+   * @deprecated Use {@link #hasNextMediaItem()} instead.
+   */
   @Deprecated
   @Override
   public final boolean hasNextWindow() {
@@ -215,12 +233,18 @@ public abstract class BasePlayer implements Player {
     return getNextMediaItemIndex() != C.INDEX_UNSET;
   }
 
+  /**
+   * @deprecated Use {@link #seekToNextMediaItem()} instead.
+   */
   @Deprecated
   @Override
   public final void next() {
     seekToNextMediaItem();
   }
 
+  /**
+   * @deprecated Use {@link #seekToNextMediaItem()} instead.
+   */
   @Deprecated
   @Override
   public final void seekToNextWindow() {
@@ -253,12 +277,18 @@ public abstract class BasePlayer implements Player {
     setPlaybackParameters(getPlaybackParameters().withSpeed(speed));
   }
 
+  /**
+   * @deprecated Use {@link #getCurrentMediaItemIndex()} instead.
+   */
   @Deprecated
   @Override
   public final int getCurrentWindowIndex() {
     return getCurrentMediaItemIndex();
   }
 
+  /**
+   * @deprecated Use {@link #getNextMediaItemIndex()} instead.
+   */
   @Deprecated
   @Override
   public final int getNextWindowIndex() {
@@ -274,6 +304,9 @@ public abstract class BasePlayer implements Player {
             getCurrentMediaItemIndex(), getRepeatModeForNavigation(), getShuffleModeEnabled());
   }
 
+  /**
+   * @deprecated Use {@link #getPreviousMediaItemIndex()} instead.
+   */
   @Deprecated
   @Override
   public final int getPreviousWindowIndex() {
@@ -326,6 +359,9 @@ public abstract class BasePlayer implements Player {
         : duration == 0 ? 100 : Util.constrainValue((int) ((position * 100) / duration), 0, 100);
   }
 
+  /**
+   * @deprecated Use {@link #isCurrentMediaItemDynamic()} instead.
+   */
   @Deprecated
   @Override
   public final boolean isCurrentWindowDynamic() {
@@ -338,6 +374,9 @@ public abstract class BasePlayer implements Player {
     return !timeline.isEmpty() && timeline.getWindow(getCurrentMediaItemIndex(), window).isDynamic;
   }
 
+  /**
+   * @deprecated Use {@link #isCurrentMediaItemLive()} instead.
+   */
   @Deprecated
   @Override
   public final boolean isCurrentWindowLive() {
@@ -364,6 +403,9 @@ public abstract class BasePlayer implements Player {
     return window.getCurrentUnixTimeMs() - window.windowStartTimeMs - getContentPosition();
   }
 
+  /**
+   * @deprecated Use {@link #isCurrentMediaItemSeekable()} instead.
+   */
   @Deprecated
   @Override
   public final boolean isCurrentWindowSeekable() {
diff --git a/libraries/common/src/main/java/androidx/media3/common/ForwardingPlayer.java b/libraries/common/src/main/java/androidx/media3/common/ForwardingPlayer.java
index b6fb7111df..5975897b40 100644
--- a/libraries/common/src/main/java/androidx/media3/common/ForwardingPlayer.java
+++ b/libraries/common/src/main/java/androidx/media3/common/ForwardingPlayer.java
@@ -299,7 +299,11 @@ public class ForwardingPlayer implements Player {
     player.seekForward();
   }
 
-  /** Calls {@link Player#hasPrevious()} on the delegate and returns the result. */
+  /**
+   * Calls {@link Player#hasPrevious()} on the delegate and returns the result.
+   *
+   * @deprecated Use {@link #hasPreviousMediaItem()} instead.
+   */
   @SuppressWarnings("deprecation") // Forwarding to deprecated method
   @Deprecated
   @Override
@@ -307,7 +311,11 @@ public class ForwardingPlayer implements Player {
     return player.hasPrevious();
   }
 
-  /** Calls {@link Player#hasPreviousWindow()} on the delegate and returns the result. */
+  /**
+   * Calls {@link Player#hasPreviousWindow()} on the delegate and returns the result.
+   *
+   * @deprecated Use {@link #hasPreviousMediaItem()} instead.
+   */
   @SuppressWarnings("deprecation") // Forwarding to deprecated method
   @Deprecated
   @Override
@@ -321,7 +329,11 @@ public class ForwardingPlayer implements Player {
     return player.hasPreviousMediaItem();
   }
 
-  /** Calls {@link Player#previous()} on the delegate. */
+  /**
+   * Calls {@link Player#previous()} on the delegate.
+   *
+   * @deprecated Use {@link #seekToPreviousMediaItem()} instead.
+   */
   @SuppressWarnings("deprecation") // Forwarding to deprecated method
   @Deprecated
   @Override
@@ -329,7 +341,11 @@ public class ForwardingPlayer implements Player {
     player.previous();
   }
 
-  /** Calls {@link Player#seekToPreviousWindow()} on the delegate. */
+  /**
+   * Calls {@link Player#seekToPreviousWindow()} on the delegate.
+   *
+   * @deprecated Use {@link #seekToPreviousMediaItem()} instead.
+   */
   @SuppressWarnings("deprecation") // Forwarding to deprecated method
   @Deprecated
   @Override
@@ -355,7 +371,11 @@ public class ForwardingPlayer implements Player {
     return player.getMaxSeekToPreviousPosition();
   }
 
-  /** Calls {@link Player#hasNext()} on the delegate and returns the result. */
+  /**
+   * Calls {@link Player#hasNext()} on the delegate and returns the result.
+   *
+   * @deprecated Use {@link #hasNextMediaItem()} instead.
+   */
   @SuppressWarnings("deprecation") // Forwarding to deprecated method
   @Deprecated
   @Override
@@ -363,7 +383,11 @@ public class ForwardingPlayer implements Player {
     return player.hasNext();
   }
 
-  /** Calls {@link Player#hasNextWindow()} on the delegate and returns the result. */
+  /**
+   * Calls {@link Player#hasNextWindow()} on the delegate and returns the result.
+   *
+   * @deprecated Use {@link #hasNextMediaItem()} instead.
+   */
   @SuppressWarnings("deprecation") // Forwarding to deprecated method
   @Deprecated
   @Override
@@ -377,7 +401,11 @@ public class ForwardingPlayer implements Player {
     return player.hasNextMediaItem();
   }
 
-  /** Calls {@link Player#next()} on the delegate. */
+  /**
+   * Calls {@link Player#next()} on the delegate.
+   *
+   * @deprecated Use {@link #seekToNextMediaItem()} instead.
+   */
   @SuppressWarnings("deprecation") // Forwarding to deprecated method
   @Deprecated
   @Override
@@ -385,7 +413,11 @@ public class ForwardingPlayer implements Player {
     player.next();
   }
 
-  /** Calls {@link Player#seekToNextWindow()} on the delegate. */
+  /**
+   * Calls {@link Player#seekToNextWindow()} on the delegate.
+   *
+   * @deprecated Use {@link #seekToNextMediaItem()} instead.
+   */
   @SuppressWarnings("deprecation") // Forwarding to deprecated method
   @Deprecated
   @Override
@@ -429,7 +461,13 @@ public class ForwardingPlayer implements Player {
     player.stop();
   }
 
-  /** Calls {@link Player#stop(boolean)} on the delegate. */
+  /**
+   * Calls {@link Player#stop(boolean)} on the delegate.
+   *
+   * @deprecated Use {@link #stop()} and {@link #clearMediaItems()} (if {@code reset} is true) or
+   *     just {@link #stop()} (if {@code reset} is false). Any player error will be cleared when
+   *     {@link #prepare() re-preparing} the player.
+   */
   @SuppressWarnings("deprecation") // Forwarding to deprecated method
   @Deprecated
   @Override
@@ -498,7 +536,11 @@ public class ForwardingPlayer implements Player {
     return player.getCurrentPeriodIndex();
   }
 
-  /** Calls {@link Player#getCurrentWindowIndex()} on the delegate and returns the result. */
+  /**
+   * Calls {@link Player#getCurrentWindowIndex()} on the delegate and returns the result.
+   *
+   * @deprecated Use {@link #getCurrentMediaItemIndex()} instead.
+   */
   @SuppressWarnings("deprecation") // Forwarding to deprecated method
   @Deprecated
   @Override
@@ -512,7 +554,11 @@ public class ForwardingPlayer implements Player {
     return player.getCurrentMediaItemIndex();
   }
 
-  /** Calls {@link Player#getNextWindowIndex()} on the delegate and returns the result. */
+  /**
+   * Calls {@link Player#getNextWindowIndex()} on the delegate and returns the result.
+   *
+   * @deprecated Use {@link #getNextMediaItemIndex()} instead.
+   */
   @SuppressWarnings("deprecation") // Forwarding to deprecated method
   @Deprecated
   @Override
@@ -526,7 +572,11 @@ public class ForwardingPlayer implements Player {
     return player.getNextMediaItemIndex();
   }
 
-  /** Calls {@link Player#getPreviousWindowIndex()} on the delegate and returns the result. */
+  /**
+   * Calls {@link Player#getPreviousWindowIndex()} on the delegate and returns the result.
+   *
+   * @deprecated Use {@link #getPreviousMediaItemIndex()} instead.
+   */
   @SuppressWarnings("deprecation") // Forwarding to deprecated method
   @Deprecated
   @Override
@@ -589,7 +639,11 @@ public class ForwardingPlayer implements Player {
     return player.getTotalBufferedDuration();
   }
 
-  /** Calls {@link Player#isCurrentWindowDynamic()} on the delegate and returns the result. */
+  /**
+   * Calls {@link Player#isCurrentWindowDynamic()} on the delegate and returns the result.
+   *
+   * @deprecated Use {@link #isCurrentMediaItemDynamic()} instead.
+   */
   @SuppressWarnings("deprecation") // Forwarding to deprecated method
   @Deprecated
   @Override
@@ -603,7 +657,11 @@ public class ForwardingPlayer implements Player {
     return player.isCurrentMediaItemDynamic();
   }
 
-  /** Calls {@link Player#isCurrentWindowLive()} on the delegate and returns the result. */
+  /**
+   * Calls {@link Player#isCurrentWindowLive()} on the delegate and returns the result.
+   *
+   * @deprecated Use {@link #isCurrentMediaItemLive()} instead.
+   */
   @SuppressWarnings("deprecation") // Forwarding to deprecated method
   @Deprecated
   @Override
@@ -623,7 +681,11 @@ public class ForwardingPlayer implements Player {
     return player.getCurrentLiveOffset();
   }
 
-  /** Calls {@link Player#isCurrentWindowSeekable()} on the delegate and returns the result. */
+  /**
+   * Calls {@link Player#isCurrentWindowSeekable()} on the delegate and returns the result.
+   *
+   * @deprecated Use {@link #isCurrentMediaItemSeekable()} instead.
+   */
   @SuppressWarnings("deprecation") // Forwarding to deprecated method
   @Deprecated
   @Override
diff --git a/libraries/datasource_cronet/src/main/java/androidx/media3/datasource/cronet/CronetDataSource.java b/libraries/datasource_cronet/src/main/java/androidx/media3/datasource/cronet/CronetDataSource.java
index 505a65033c..056ece7591 100644
--- a/libraries/datasource_cronet/src/main/java/androidx/media3/datasource/cronet/CronetDataSource.java
+++ b/libraries/datasource_cronet/src/main/java/androidx/media3/datasource/cronet/CronetDataSource.java
@@ -481,11 +481,7 @@ public class CronetDataSource extends BaseDataSource implements HttpDataSource {
   }
 
   /**
-   * Sets a content type {@link Predicate}. If a content type is rejected by the predicate then a
-   * {@link HttpDataSource.InvalidContentTypeException} is thrown from {@link #open(DataSpec)}.
-   *
-   * @param contentTypePredicate The content type {@link Predicate}, or {@code null} to clear a
-   *     predicate that was previously set.
+   * @deprecated Use {@link CronetDataSource.Factory#setContentTypePredicate(Predicate)} instead.
    */
   @UnstableApi
   @Deprecated
diff --git a/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/SimpleExoPlayer.java b/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/SimpleExoPlayer.java
index 3d4a315ab3..3dfd26d19b 100644
--- a/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/SimpleExoPlayer.java
+++ b/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/SimpleExoPlayer.java
@@ -33,6 +33,7 @@ import androidx.media3.common.Format;
 import androidx.media3.common.MediaItem;
 import androidx.media3.common.MediaMetadata;
 import androidx.media3.common.PlaybackParameters;
+import androidx.media3.common.Player;
 import androidx.media3.common.PriorityTaskManager;
 import androidx.media3.common.Timeline;
 import androidx.media3.common.TrackSelectionParameters;
@@ -426,24 +427,44 @@ public class SimpleExoPlayer extends BasePlayer
     return player.experimentalIsSleepingForOffload();
   }
 
+  /**
+   * @deprecated Use {@link ExoPlayer}, as the {@link AudioComponent} methods are defined by that
+   *     interface.
+   */
+  @Deprecated
   @Override
   @Nullable
   public AudioComponent getAudioComponent() {
     return this;
   }
 
+  /**
+   * @deprecated Use {@link ExoPlayer}, as the {@link VideoComponent} methods are defined by that
+   *     interface.
+   */
+  @Deprecated
   @Override
   @Nullable
   public VideoComponent getVideoComponent() {
     return this;
   }
 
+  /**
+   * @deprecated Use {@link Player}, as the {@link TextComponent} methods are defined by that
+   *     interface.
+   */
+  @Deprecated
   @Override
   @Nullable
   public TextComponent getTextComponent() {
     return this;
   }
 
+  /**
+   * @deprecated Use {@link Player}, as the {@link DeviceComponent} methods are defined by that
+   *     interface.
+   */
+  @Deprecated
   @Override
   @Nullable
   public DeviceComponent getDeviceComponent() {
@@ -1003,6 +1024,11 @@ public class SimpleExoPlayer extends BasePlayer
     player.stop();
   }
 
+  /**
+   * @deprecated Use {@link #stop()} and {@link #clearMediaItems()} (if {@code reset} is true) or
+   *     just {@link #stop()} (if {@code reset} is false). Any player error will be cleared when
+   *     {@link #prepare() re-preparing} the player.
+   */
   @Deprecated
   @Override
   public void stop(boolean reset) {
@@ -1046,12 +1072,20 @@ public class SimpleExoPlayer extends BasePlayer
     return player.getTrackSelector();
   }
 
+  /**
+   * @deprecated Use {@link #getCurrentTracks()}.
+   */
+  @Deprecated
   @Override
   public TrackGroupArray getCurrentTrackGroups() {
     blockUntilConstructorFinished();
     return player.getCurrentTrackGroups();
   }
 
+  /**
+   * @deprecated Use {@link #getCurrentTracks()}.
+   */
+  @Deprecated
   @Override
   public TrackSelectionArray getCurrentTrackSelections() {
     blockUntilConstructorFinished();
@@ -1166,6 +1200,9 @@ public class SimpleExoPlayer extends BasePlayer
     return player.getContentBufferedPosition();
   }
 
+  /**
+   * @deprecated Use {@link #setWakeMode(int)} instead.
+   */
   @Deprecated
   @Override
   public void setHandleWakeLock(boolean handleWakeLock) {
diff --git a/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/trackselection/DefaultTrackSelector.java b/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/trackselection/DefaultTrackSelector.java
index 35b886927e..8e45ec3135 100644
--- a/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/trackselection/DefaultTrackSelector.java
+++ b/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/trackselection/DefaultTrackSelector.java
@@ -616,6 +616,9 @@ public class DefaultTrackSelector extends MappingTrackSelector {
       return this;
     }
 
+    /**
+     * @deprecated Use {@link #setTrackTypeDisabled(int, boolean)}.
+     */
     @Override
     @Deprecated
     @SuppressWarnings("deprecation")
diff --git a/libraries/session/src/main/java/androidx/media3/session/MediaController.java b/libraries/session/src/main/java/androidx/media3/session/MediaController.java
index 8f5a0424b7..348750b813 100644
--- a/libraries/session/src/main/java/androidx/media3/session/MediaController.java
+++ b/libraries/session/src/main/java/androidx/media3/session/MediaController.java
@@ -401,6 +401,11 @@ public class MediaController implements Player {
     impl.stop();
   }
 
+  /**
+   * @deprecated Use {@link #stop()} and {@link #clearMediaItems()} (if {@code reset} is true) or
+   *     just {@link #stop()} (if {@code reset} is false). Any player error will be cleared when
+   *     {@link #prepare() re-preparing} the player.
+   */
   @UnstableApi
   @Deprecated
   @Override
@@ -1185,6 +1190,9 @@ public class MediaController implements Player {
     impl.moveMediaItems(fromIndex, toIndex, newIndex);
   }
 
+  /**
+   * @deprecated Use {@link #isCurrentMediaItemDynamic()} instead.
+   */
   @UnstableApi
   @Deprecated
   @Override
@@ -1199,6 +1207,9 @@ public class MediaController implements Player {
     return !timeline.isEmpty() && timeline.getWindow(getCurrentMediaItemIndex(), window).isDynamic;
   }
 
+  /**
+   * @deprecated Use {@link #isCurrentMediaItemLive()} instead.
+   */
   @UnstableApi
   @Deprecated
   @Override
@@ -1213,6 +1224,9 @@ public class MediaController implements Player {
     return !timeline.isEmpty() && timeline.getWindow(getCurrentMediaItemIndex(), window).isLive();
   }
 
+  /**
+   * @deprecated Use {@link #isCurrentMediaItemSeekable()} instead.
+   */
   @UnstableApi
   @Deprecated
   @Override
@@ -1262,6 +1276,9 @@ public class MediaController implements Player {
     return isConnected() ? impl.getCurrentPeriodIndex() : C.INDEX_UNSET;
   }
 
+  /**
+   * @deprecated Use {@link #getCurrentMediaItemIndex()} instead.
+   */
   @UnstableApi
   @Deprecated
   @Override
@@ -1275,6 +1292,9 @@ public class MediaController implements Player {
     return isConnected() ? impl.getCurrentMediaItemIndex() : C.INDEX_UNSET;
   }
 
+  /**
+   * @deprecated Use {@link #getPreviousMediaItemIndex()} instead.
+   */
   @UnstableApi
   @Deprecated
   @Override
@@ -1295,6 +1315,9 @@ public class MediaController implements Player {
     return isConnected() ? impl.getPreviousMediaItemIndex() : C.INDEX_UNSET;
   }
 
+  /**
+   * @deprecated Use {@link #getNextMediaItemIndex()} instead.
+   */
   @UnstableApi
   @Deprecated
   @Override
@@ -1315,6 +1338,9 @@ public class MediaController implements Player {
     return isConnected() ? impl.getNextMediaItemIndex() : C.INDEX_UNSET;
   }
 
+  /**
+   * @deprecated Use {@link #hasPreviousMediaItem()} instead.
+   */
   @UnstableApi
   @Deprecated
   @Override
@@ -1322,6 +1348,9 @@ public class MediaController implements Player {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #hasNextMediaItem()} instead.
+   */
   @UnstableApi
   @Deprecated
   @Override
@@ -1329,6 +1358,9 @@ public class MediaController implements Player {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #hasPreviousMediaItem()} instead.
+   */
   @UnstableApi
   @Deprecated
   @Override
@@ -1336,6 +1368,9 @@ public class MediaController implements Player {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #hasNextMediaItem()} instead.
+   */
   @UnstableApi
   @Deprecated
   @Override
@@ -1355,6 +1390,9 @@ public class MediaController implements Player {
     return isConnected() && impl.hasNextMediaItem();
   }
 
+  /**
+   * @deprecated Use {@link #seekToPreviousMediaItem()} instead.
+   */
   @UnstableApi
   @Deprecated
   @Override
@@ -1362,6 +1400,9 @@ public class MediaController implements Player {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #seekToNextMediaItem()} instead.
+   */
   @UnstableApi
   @Deprecated
   @Override
@@ -1369,6 +1410,9 @@ public class MediaController implements Player {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #seekToPreviousMediaItem()} instead.
+   */
   @UnstableApi
   @Deprecated
   @Override
@@ -1392,6 +1436,9 @@ public class MediaController implements Player {
     impl.seekToPreviousMediaItem();
   }
 
+  /**
+   * @deprecated Use {@link #seekToNextMediaItem()} instead.
+   */
   @UnstableApi
   @Deprecated
   @Override
diff --git a/libraries/test_session_current/src/main/java/androidx/media3/session/MockPlayer.java b/libraries/test_session_current/src/main/java/androidx/media3/session/MockPlayer.java
index 693a380119..d9a9258b65 100644
--- a/libraries/test_session_current/src/main/java/androidx/media3/session/MockPlayer.java
+++ b/libraries/test_session_current/src/main/java/androidx/media3/session/MockPlayer.java
@@ -310,6 +310,11 @@ public class MockPlayer implements Player {
     checkNotNull(conditionVariables.get(METHOD_STOP)).open();
   }
 
+  /**
+   * @deprecated Use {@link #stop()} and {@link #clearMediaItems()} (if {@code reset} is true) or
+   *     just {@link #stop()} (if {@code reset} is false). Any player error will be cleared when
+   *     {@link #prepare() re-preparing} the player.
+   */
   @Deprecated
   @Override
   public void stop(boolean reset) {
@@ -758,6 +763,9 @@ public class MockPlayer implements Player {
     checkNotNull(conditionVariables.get(METHOD_SET_PLAYLIST_METADATA)).open();
   }
 
+  /**
+   * @deprecated Use {@link #isCurrentMediaItemDynamic()} instead.
+   */
   @Deprecated
   @Override
   public boolean isCurrentWindowDynamic() {
@@ -769,6 +777,9 @@ public class MockPlayer implements Player {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #isCurrentMediaItemLive()} instead.
+   */
   @Deprecated
   @Override
   public boolean isCurrentWindowLive() {
@@ -780,6 +791,9 @@ public class MockPlayer implements Player {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #isCurrentMediaItemSeekable()} instead.
+   */
   @Deprecated
   @Override
   public boolean isCurrentWindowSeekable() {
@@ -815,6 +829,9 @@ public class MockPlayer implements Player {
     return currentPeriodIndex;
   }
 
+  /**
+   * @deprecated Use {@link #getCurrentMediaItemIndex()} instead.
+   */
   @Deprecated
   @Override
   public int getCurrentWindowIndex() {
@@ -826,6 +843,9 @@ public class MockPlayer implements Player {
     return currentMediaItemIndex;
   }
 
+  /**
+   * @deprecated Use {@link #getPreviousMediaItemIndex()} instead.
+   */
   @Deprecated
   @Override
   public int getPreviousWindowIndex() {
@@ -837,6 +857,9 @@ public class MockPlayer implements Player {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #getNextMediaItemIndex()} instead.
+   */
   @Deprecated
   @Override
   public int getNextWindowIndex() {
@@ -912,24 +935,36 @@ public class MockPlayer implements Player {
     checkNotNull(conditionVariables.get(METHOD_MOVE_MEDIA_ITEMS)).open();
   }
 
+  /**
+   * @deprecated Use {@link #hasPreviousMediaItem()} instead.
+   */
   @Deprecated
   @Override
   public boolean hasPrevious() {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #hasNextMediaItem()} instead.
+   */
   @Deprecated
   @Override
   public boolean hasNext() {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #hasPreviousMediaItem()} instead.
+   */
   @Deprecated
   @Override
   public boolean hasPreviousWindow() {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #hasNextMediaItem()} instead.
+   */
   @Deprecated
   @Override
   public boolean hasNextWindow() {
@@ -946,24 +981,36 @@ public class MockPlayer implements Player {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #seekToPreviousMediaItem()} instead.
+   */
   @Deprecated
   @Override
   public void previous() {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #seekToNextMediaItem()} instead.
+   */
   @Deprecated
   @Override
   public void next() {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #seekToPreviousMediaItem()} instead.
+   */
   @Deprecated
   @Override
   public void seekToPreviousWindow() {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #seekToNextMediaItem()} instead.
+   */
   @Deprecated
   @Override
   public void seekToNextWindow() {
diff --git a/libraries/test_utils/src/main/java/androidx/media3/test/utils/StubExoPlayer.java b/libraries/test_utils/src/main/java/androidx/media3/test/utils/StubExoPlayer.java
index ee75dc9d73..28840d6ae0 100644
--- a/libraries/test_utils/src/main/java/androidx/media3/test/utils/StubExoPlayer.java
+++ b/libraries/test_utils/src/main/java/androidx/media3/test/utils/StubExoPlayer.java
@@ -20,6 +20,7 @@ import androidx.annotation.Nullable;
 import androidx.media3.common.AudioAttributes;
 import androidx.media3.common.AuxEffectInfo;
 import androidx.media3.common.Format;
+import androidx.media3.common.Player;
 import androidx.media3.common.PriorityTaskManager;
 import androidx.media3.common.util.Clock;
 import androidx.media3.common.util.UnstableApi;
@@ -47,24 +48,40 @@ import java.util.List;
 @UnstableApi
 public class StubExoPlayer extends StubPlayer implements ExoPlayer {
 
+  /**
+   * @deprecated Use {@link ExoPlayer}, as the {@link AudioComponent} methods are defined by that
+   *     interface.
+   */
   @Override
   @Deprecated
   public AudioComponent getAudioComponent() {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link ExoPlayer}, as the {@link VideoComponent} methods are defined by that
+   *     interface.
+   */
   @Override
   @Deprecated
   public VideoComponent getVideoComponent() {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link Player}, as the {@link TextComponent} methods are defined by that
+   *     interface.
+   */
   @Override
   @Deprecated
   public TextComponent getTextComponent() {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link Player}, as the {@link DeviceComponent} methods are defined by that
+   *     interface.
+   */
   @Override
   @Deprecated
   public DeviceComponent getDeviceComponent() {
@@ -111,18 +128,27 @@ public class StubExoPlayer extends StubPlayer implements ExoPlayer {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #prepare()} instead.
+   */
   @Deprecated
   @Override
   public void retry() {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #setMediaSource(MediaSource)} and {@link #prepare()} instead.
+   */
   @Deprecated
   @Override
   public void prepare(MediaSource mediaSource) {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #setMediaSource(MediaSource, boolean)} and {@link #prepare()} instead.
+   */
   @Deprecated
   @Override
   public void prepare(MediaSource mediaSource, boolean resetPosition, boolean resetState) {
@@ -296,11 +322,19 @@ public class StubExoPlayer extends StubPlayer implements ExoPlayer {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #getCurrentTracks()}.
+   */
+  @Deprecated
   @Override
   public TrackGroupArray getCurrentTrackGroups() {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #getCurrentTracks()}.
+   */
+  @Deprecated
   @Override
   public TrackSelectionArray getCurrentTrackSelections() {
     throw new UnsupportedOperationException();
@@ -350,6 +384,9 @@ public class StubExoPlayer extends StubPlayer implements ExoPlayer {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #setWakeMode(int)} instead.
+   */
   @Deprecated
   @Override
   public void setHandleWakeLock(boolean handleWakeLock) {
diff --git a/libraries/test_utils/src/main/java/androidx/media3/test/utils/StubPlayer.java b/libraries/test_utils/src/main/java/androidx/media3/test/utils/StubPlayer.java
index 5787019136..85569df265 100644
--- a/libraries/test_utils/src/main/java/androidx/media3/test/utils/StubPlayer.java
+++ b/libraries/test_utils/src/main/java/androidx/media3/test/utils/StubPlayer.java
@@ -179,6 +179,11 @@ public class StubPlayer extends BasePlayer {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #stop()} and {@link #clearMediaItems()} (if {@code reset} is true) or
+   *     just {@link #stop()} (if {@code reset} is false). Any player error will be cleared when
+   *     {@link #prepare() re-preparing} the player.
+   */
   @Deprecated
   @Override
   public void stop(boolean reset) {