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
(cherry picked from commit d711dee003c9f7d8a3f31031b35a4121d0db6f09)

extensions/cast/src/main/java/com/google/android/exoplayer2/ext/cast/CastPlayer.java

@@ -456,6 +456,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) {

extensions/cronet/src/main/java/com/google/android/exoplayer2/ext/cronet/CronetDataSource.java

@@ -465,11 +465,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
+   * @deprecated Use {@link CronetDataSource.Factory#setContentTypePredicate(Predicate)} instead.
-   * {@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
   public void setContentTypePredicate(@Nullable Predicate<String> contentTypePredicate) {

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

@@ -141,12 +141,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() {
@@ -158,12 +164,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() {
@@ -196,12 +208,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() {
@@ -213,12 +231,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() {
@@ -251,12 +275,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() {
@@ -272,6 +302,9 @@ public abstract class BasePlayer implements Player {
             getCurrentMediaItemIndex(), getRepeatModeForNavigation(), getShuffleModeEnabled());
   }
 
+  /**
+   * @deprecated Use {@link #getPreviousMediaItemIndex()} instead.
+   */
   @Deprecated
   @Override
   public final int getPreviousWindowIndex() {
@@ -324,6 +357,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() {
@@ -336,6 +372,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() {
@@ -362,6 +401,9 @@ public abstract class BasePlayer implements Player {
     return window.getCurrentUnixTimeMs() - window.windowStartTimeMs - getContentPosition();
   }
 
+  /**
+   * @deprecated Use {@link #isCurrentMediaItemSeekable()} instead.
+   */
   @Deprecated
   @Override
   public final boolean isCurrentWindowSeekable() {

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

@@ -301,7 +301,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
@@ -309,7 +313,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
@@ -323,7 +331,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
@@ -331,7 +343,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
@@ -357,7 +373,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
@@ -365,7 +385,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
@@ -379,7 +403,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
@@ -387,7 +415,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
@@ -431,7 +463,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
@@ -500,7 +538,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
@@ -514,7 +556,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
@@ -528,7 +574,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
@@ -591,7 +641,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
@@ -605,7 +659,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
@@ -625,7 +683,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

library/core/src/main/java/com/google/android/exoplayer2/SimpleExoPlayer.java

@@ -416,24 +416,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() {
@@ -993,6 +1013,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) {
@@ -1036,12 +1061,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();
@@ -1156,6 +1189,9 @@ public class SimpleExoPlayer extends BasePlayer
     return player.getContentBufferedPosition();
   }
 
+  /**
+   * @deprecated Use {@link #setWakeMode(int)} instead.
+   */
   @Deprecated
   @Override
   public void setHandleWakeLock(boolean handleWakeLock) {

library/core/src/main/java/com/google/android/exoplayer2/trackselection/DefaultTrackSelector.java

@@ -612,6 +612,9 @@ public class DefaultTrackSelector extends MappingTrackSelector {
       return this;
     }
 
+    /**
+     * @deprecated Use {@link #setTrackTypeDisabled(int, boolean)}.
+     */
     @Override
     @Deprecated
     @SuppressWarnings("deprecation")

testutils/src/main/java/com/google/android/exoplayer2/testutil/StubExoPlayer.java

@@ -20,6 +20,7 @@ import androidx.annotation.Nullable;
 import com.google.android.exoplayer2.ExoPlaybackException;
 import com.google.android.exoplayer2.ExoPlayer;
 import com.google.android.exoplayer2.Format;
+import com.google.android.exoplayer2.Player;
 import com.google.android.exoplayer2.PlayerMessage;
 import com.google.android.exoplayer2.Renderer;
 import com.google.android.exoplayer2.SeekParameters;
@@ -45,24 +46,40 @@ import java.util.List;
  */
 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() {
@@ -109,18 +126,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) {
@@ -294,11 +320,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();
@@ -348,6 +382,9 @@ public class StubExoPlayer extends StubPlayer implements ExoPlayer {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * @deprecated Use {@link #setWakeMode(int)} instead.
+   */
   @Deprecated
   @Override
   public void setHandleWakeLock(boolean handleWakeLock) {

testutils/src/main/java/com/google/android/exoplayer2/testutil/StubPlayer.java

@@ -177,6 +177,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) {