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
androidx · May 31, 2022 · b8ca5b8 · b8ca5b8
1 parent 87ab96d
commit b8ca5b8
Show file tree

Hide file tree

Showing 10 changed files with 301 additions and 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
@@ -458,6 +458,11 @@ public void stop() {
     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
@@ -143,12 +143,18 @@ public final void seekForward() {
     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 final boolean hasPreviousMediaItem() {
     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 final void seekToPrevious() {
     }
   }
 
+  /**
+   * @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 final boolean hasNextMediaItem() {
     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 final void setPlaybackSpeed(float speed) {
     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 final int getNextMediaItemIndex() {
             getCurrentMediaItemIndex(), getRepeatModeForNavigation(), getShuffleModeEnabled());
   }
 
+  /**
+   * @deprecated Use {@link #getPreviousMediaItemIndex()} instead.
+   */
   @Deprecated
   @Override
   public final int getPreviousWindowIndex() {
@@ -326,6 +359,9 @@ public final int getBufferedPercentage() {
         : 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 final boolean isCurrentMediaItemDynamic() {
     return !timeline.isEmpty() && timeline.getWindow(getCurrentMediaItemIndex(), window).isDynamic;
   }
 
+  /**
+   * @deprecated Use {@link #isCurrentMediaItemLive()} instead.
+   */
   @Deprecated
   @Override
   public final boolean isCurrentWindowLive() {
@@ -364,6 +403,9 @@ public final long getCurrentLiveOffset() {
     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
@@ -299,15 +299,23 @@ public void seekForward() {
     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
   public boolean hasPrevious() {
     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,15 +329,23 @@ public boolean hasPreviousMediaItem() {
     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
   public void previous() {
     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,15 +371,23 @@ public long getMaxSeekToPreviousPosition() {
     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
   public boolean hasNext() {
     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,15 +401,23 @@ public boolean hasNextMediaItem() {
     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
   public void next() {
     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 void stop() {
     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 int getCurrentPeriodIndex() {
     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 int getCurrentMediaItemIndex() {
     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 int getNextMediaItemIndex() {
     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 long getTotalBufferedDuration() {
     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 boolean isCurrentMediaItemDynamic() {
     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 long getCurrentLiveOffset() {
     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/...s/datasource_cronet/src/main/java/androidx/media3/datasource/cronet/CronetDataSource.java b/...s/datasource_cronet/src/main/java/androidx/media3/datasource/cronet/CronetDataSource.java
@@ -481,11 +481,7 @@ protected CronetDataSource(
   }
 
   /**
-   * 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