Improve Player next/previous documentation

#exofixit
Issue: #5602
PiperOrigin-RevId: 344093622

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

@@ -867,15 +867,21 @@ public interface Player {
   @IntDef({REPEAT_MODE_OFF, REPEAT_MODE_ONE, REPEAT_MODE_ALL})
   @IntDef({REPEAT_MODE_OFF, REPEAT_MODE_ONE, REPEAT_MODE_ALL})
   @interface RepeatMode {}
   @interface RepeatMode {}
   /**
   /**
-   * Normal playback without repetition.
+   * Normal playback without repetition. "Previous" and "Next" actions move to the previous and next
+   * windows respectively, and do nothing when there is no previous or next window to move to.
    */
    */
   int REPEAT_MODE_OFF = 0;
   int REPEAT_MODE_OFF = 0;
   /**
   /**
-   * "Repeat One" mode to repeat the currently playing window infinitely.
+   * Repeats the currently playing window infinitely during ongoing playback. "Previous" and "Next"
+   * actions behave as they do in {@link #REPEAT_MODE_OFF}, moving to the previous and next windows
+   * respectively, and doing nothing when there is no previous or next window to move to.
    */
    */
   int REPEAT_MODE_ONE = 1;
   int REPEAT_MODE_ONE = 1;
   /**
   /**
-   * "Repeat All" mode to repeat the entire timeline infinitely.
+   * Repeats the entire timeline infinitely. "Previous" and "Next" actions behave as they do in
+   * {@link #REPEAT_MODE_OFF}, but with looping at the ends so that "Previous" when playing the
+   * first window will move to the last window, and "Next" when playing the last window will move to
+   * the first window.
    */
    */
   int REPEAT_MODE_ALL = 2;
   int REPEAT_MODE_ALL = 2;
 
 
@@ -1328,26 +1334,41 @@ public interface Player {
   /**
   /**
    * Returns whether a previous window exists, which may depend on the current repeat mode and
    * Returns whether a previous window exists, which may depend on the current repeat mode and
    * whether shuffle mode is enabled.
    * whether shuffle mode is enabled.
+   *
+   * <p>Note: When the repeat mode is {@link #REPEAT_MODE_ONE}, this method behaves the same as when
+   * the current repeat mode is {@link #REPEAT_MODE_OFF}. See {@link #REPEAT_MODE_ONE} for more
+   * details.
    */
    */
   boolean hasPrevious();
   boolean hasPrevious();
 
 
   /**
   /**
-   * Seeks to the default position of the previous window in the timeline, which may depend on the
-   * current repeat mode and whether shuffle mode is enabled. Does nothing if {@link #hasPrevious()}
-   * is {@code false}.
+   * Seeks to the default position of the previous window, which may depend on the current repeat
+   * mode and whether shuffle mode is enabled. Does nothing if {@link #hasPrevious()} is {@code
+   * false}.
+   *
+   * <p>Note: When the repeat mode is {@link #REPEAT_MODE_ONE}, this method behaves the same as when
+   * the current repeat mode is {@link #REPEAT_MODE_OFF}. See {@link #REPEAT_MODE_ONE} for more
+   * details.
    */
    */
   void previous();
   void previous();
 
 
   /**
   /**
    * Returns whether a next window exists, which may depend on the current repeat mode and whether
    * Returns whether a next window exists, which may depend on the current repeat mode and whether
    * shuffle mode is enabled.
    * shuffle mode is enabled.
+   *
+   * <p>Note: When the repeat mode is {@link #REPEAT_MODE_ONE}, this method behaves the same as when
+   * the current repeat mode is {@link #REPEAT_MODE_OFF}. See {@link #REPEAT_MODE_ONE} for more
+   * details.
    */
    */
   boolean hasNext();
   boolean hasNext();
 
 
   /**
   /**
-   * Seeks to the default position of the next window in the timeline, which may depend on the
-   * current repeat mode and whether shuffle mode is enabled. Does nothing if {@link #hasNext()} is
-   * {@code false}.
+   * Seeks to the default position of the next window, which may depend on the current repeat mode
+   * and whether shuffle mode is enabled. Does nothing if {@link #hasNext()} is {@code false}.
+   *
+   * <p>Note: When the repeat mode is {@link #REPEAT_MODE_ONE}, this method behaves the same as when
+   * the current repeat mode is {@link #REPEAT_MODE_OFF}. See {@link #REPEAT_MODE_ONE} for more
+   * details.
    */
    */
   void next();
   void next();
 
 
@@ -1465,18 +1486,24 @@ public interface Player {
   int getCurrentWindowIndex();
   int getCurrentWindowIndex();
 
 
   /**
   /**
-   * Returns the index of the next timeline window to be played, which may depend on the current
-   * repeat mode and whether shuffle mode is enabled. Returns {@link C#INDEX_UNSET} if the window
-   * currently being played is the last window or if the {@link #getCurrentTimeline() current
-   * timeline} is empty.
+   * Returns the index of the window that will be played if {@link #next()} is called, which may
+   * depend on the current repeat mode and whether shuffle mode is enabled. Returns {@link
+   * C#INDEX_UNSET} if {@link #hasNext()} is {@code false}.
+   *
+   * <p>Note: When the repeat mode is {@link #REPEAT_MODE_ONE}, this method behaves the same as when
+   * the current repeat mode is {@link #REPEAT_MODE_OFF}. See {@link #REPEAT_MODE_ONE} for more
+   * details.
    */
    */
   int getNextWindowIndex();
   int getNextWindowIndex();
 
 
   /**
   /**
-   * Returns the index of the previous timeline window to be played, which may depend on the current
-   * repeat mode and whether shuffle mode is enabled. Returns {@link C#INDEX_UNSET} if the window
-   * currently being played is the first window or if the {@link #getCurrentTimeline() current
-   * timeline} is empty.
+   * Returns the index of the window that will be played if {@link #previous()} is called, which may
+   * depend on the current repeat mode and whether shuffle mode is enabled. Returns {@link
+   * C#INDEX_UNSET} if {@link #hasPrevious()} is {@code false}.
+   *
+   * <p>Note: When the repeat mode is {@link #REPEAT_MODE_ONE}, this method behaves the same as when
+   * the current repeat mode is {@link #REPEAT_MODE_OFF}. See {@link #REPEAT_MODE_ONE} for more
+   * details.
    */
    */
   int getPreviousWindowIndex();
   int getPreviousWindowIndex();