Improve JavaDoc and method discovery for onEvents

Mentioning the realtionship on every other callback makes
it easier for the casual developer to understand the
relationship between the methods and discover the existence
of onEvents.

PiperOrigin-RevId: 343811032

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

@@ -440,6 +440,9 @@ public interface Player {
      * added or removed from the timeline. This will <em>not</em> be reported via a separate call to
      * added or removed from the timeline. This will <em>not</em> be reported via a separate call to
      * {@link #onPositionDiscontinuity(int)}.
      * {@link #onPositionDiscontinuity(int)}.
      *
      *
+     * <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
+     * other events that happen in the same {@link Looper} message queue iteration.
+     *
      * @param timeline The latest timeline. Never null, but may be empty.
      * @param timeline The latest timeline. Never null, but may be empty.
      * @param reason The {@link TimelineChangeReason} responsible for this timeline change.
      * @param reason The {@link TimelineChangeReason} responsible for this timeline change.
      */
      */
@@ -482,6 +485,9 @@ public interface Player {
      * <p>Note that this callback is also called when the playlist becomes non-empty or empty as a
      * <p>Note that this callback is also called when the playlist becomes non-empty or empty as a
      * consequence of a playlist change.
      * consequence of a playlist change.
      *
      *
+     * <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
+     * other events that happen in the same {@link Looper} message queue iteration.
+     *
      * @param mediaItem The {@link MediaItem}. May be null if the playlist becomes empty.
      * @param mediaItem The {@link MediaItem}. May be null if the playlist becomes empty.
      * @param reason The reason for the transition.
      * @param reason The reason for the transition.
      */
      */
@@ -491,6 +497,9 @@ public interface Player {
     /**
     /**
      * Called when the available or selected tracks change.
      * Called when the available or selected tracks change.
      *
      *
+     * <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
+     * other events that happen in the same {@link Looper} message queue iteration.
+     *
      * @param trackGroups The available tracks. Never null, but may be of length zero.
      * @param trackGroups The available tracks. Never null, but may be of length zero.
      * @param trackSelections The track selections for each renderer. Never null and always of
      * @param trackSelections The track selections for each renderer. Never null and always of
      *     length {@link #getRendererCount()}, but may contain null elements.
      *     length {@link #getRendererCount()}, but may contain null elements.
@@ -510,6 +519,9 @@ public interface Player {
      * Formats, rather than being timed (or dynamic) metadata, which is represented within a
      * Formats, rather than being timed (or dynamic) metadata, which is represented within a
      * metadata track.
      * metadata track.
      *
      *
+     * <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
+     * other events that happen in the same {@link Looper} message queue iteration.
+     *
      * @param metadataList The static metadata.
      * @param metadataList The static metadata.
      */
      */
     default void onStaticMetadataChanged(List<Metadata> metadataList) {}
     default void onStaticMetadataChanged(List<Metadata> metadataList) {}
@@ -517,6 +529,9 @@ public interface Player {
     /**
     /**
      * Called when the player starts or stops loading the source.
      * Called when the player starts or stops loading the source.
      *
      *
+     * <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
+     * other events that happen in the same {@link Looper} message queue iteration.
+     *
      * @param isLoading Whether the source is currently being loaded.
      * @param isLoading Whether the source is currently being loaded.
      */
      */
     @SuppressWarnings("deprecation")
     @SuppressWarnings("deprecation")
@@ -538,6 +553,9 @@ public interface Player {
     /**
     /**
      * Called when the value returned from {@link #getPlaybackState()} changes.
      * Called when the value returned from {@link #getPlaybackState()} changes.
      *
      *
+     * <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
+     * other events that happen in the same {@link Looper} message queue iteration.
+     *
      * @param state The new playback {@link State state}.
      * @param state The new playback {@link State state}.
      */
      */
     default void onPlaybackStateChanged(@State int state) {}
     default void onPlaybackStateChanged(@State int state) {}
@@ -545,6 +563,9 @@ public interface Player {
     /**
     /**
      * Called when the value returned from {@link #getPlayWhenReady()} changes.
      * Called when the value returned from {@link #getPlayWhenReady()} changes.
      *
      *
+     * <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
+     * other events that happen in the same {@link Looper} message queue iteration.
+     *
      * @param playWhenReady Whether playback will proceed when ready.
      * @param playWhenReady Whether playback will proceed when ready.
      * @param reason The {@link PlayWhenReadyChangeReason reason} for the change.
      * @param reason The {@link PlayWhenReadyChangeReason reason} for the change.
      */
      */
@@ -554,6 +575,9 @@ public interface Player {
     /**
     /**
      * Called when the value returned from {@link #getPlaybackSuppressionReason()} changes.
      * Called when the value returned from {@link #getPlaybackSuppressionReason()} changes.
      *
      *
+     * <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
+     * other events that happen in the same {@link Looper} message queue iteration.
+     *
      * @param playbackSuppressionReason The current {@link PlaybackSuppressionReason}.
      * @param playbackSuppressionReason The current {@link PlaybackSuppressionReason}.
      */
      */
     default void onPlaybackSuppressionReasonChanged(
     default void onPlaybackSuppressionReasonChanged(
@@ -562,6 +586,9 @@ public interface Player {
     /**
     /**
      * Called when the value of {@link #isPlaying()} changes.
      * Called when the value of {@link #isPlaying()} changes.
      *
      *
+     * <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
+     * other events that happen in the same {@link Looper} message queue iteration.
+     *
      * @param isPlaying Whether the player is playing.
      * @param isPlaying Whether the player is playing.
      */
      */
     default void onIsPlayingChanged(boolean isPlaying) {}
     default void onIsPlayingChanged(boolean isPlaying) {}
@@ -569,6 +596,9 @@ public interface Player {
     /**
     /**
      * Called when the value of {@link #getRepeatMode()} changes.
      * Called when the value of {@link #getRepeatMode()} changes.
      *
      *
+     * <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
+     * other events that happen in the same {@link Looper} message queue iteration.
+     *
      * @param repeatMode The {@link RepeatMode} used for playback.
      * @param repeatMode The {@link RepeatMode} used for playback.
      */
      */
     default void onRepeatModeChanged(@RepeatMode int repeatMode) {}
     default void onRepeatModeChanged(@RepeatMode int repeatMode) {}
@@ -576,6 +606,9 @@ public interface Player {
     /**
     /**
      * Called when the value of {@link #getShuffleModeEnabled()} changes.
      * Called when the value of {@link #getShuffleModeEnabled()} changes.
      *
      *
+     * <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
+     * other events that happen in the same {@link Looper} message queue iteration.
+     *
      * @param shuffleModeEnabled Whether shuffling of windows is enabled.
      * @param shuffleModeEnabled Whether shuffling of windows is enabled.
      */
      */
     default void onShuffleModeEnabledChanged(boolean shuffleModeEnabled) {}
     default void onShuffleModeEnabledChanged(boolean shuffleModeEnabled) {}
@@ -585,6 +618,9 @@ public interface Player {
      * immediately after this method is called. The player instance can still be used, and {@link
      * immediately after this method is called. The player instance can still be used, and {@link
      * #release()} must still be called on the player should it no longer be required.
      * #release()} must still be called on the player should it no longer be required.
      *
      *
+     * <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
+     * other events that happen in the same {@link Looper} message queue iteration.
+     *
      * @param error The error.
      * @param error The error.
      */
      */
     default void onPlayerError(ExoPlaybackException error) {}
     default void onPlayerError(ExoPlaybackException error) {}
@@ -599,6 +635,9 @@ public interface Player {
      * <p>When a position discontinuity occurs as a result of a change to the timeline this method
      * <p>When a position discontinuity occurs as a result of a change to the timeline this method
      * is <em>not</em> called. {@link #onTimelineChanged(Timeline, int)} is called in this case.
      * is <em>not</em> called. {@link #onTimelineChanged(Timeline, int)} is called in this case.
      *
      *
+     * <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
+     * other events that happen in the same {@link Looper} message queue iteration.
+     *
      * @param reason The {@link DiscontinuityReason} responsible for the discontinuity.
      * @param reason The {@link DiscontinuityReason} responsible for the discontinuity.
      */
      */
     default void onPositionDiscontinuity(@DiscontinuityReason int reason) {}
     default void onPositionDiscontinuity(@DiscontinuityReason int reason) {}
@@ -609,6 +648,9 @@ public interface Player {
      * them (for example, if audio playback switches to passthrough or offload mode, where speed
      * them (for example, if audio playback switches to passthrough or offload mode, where speed
      * adjustment is no longer possible).
      * adjustment is no longer possible).
      *
      *
+     * <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
+     * other events that happen in the same {@link Looper} message queue iteration.
+     *
      * @param playbackParameters The playback parameters.
      * @param playbackParameters The playback parameters.
      */
      */
     default void onPlaybackParametersChanged(PlaybackParameters playbackParameters) {}
     default void onPlaybackParametersChanged(PlaybackParameters playbackParameters) {}