From 7d3399764eebd86f9e2dac9a66eba6b3bc05b955 Mon Sep 17 00:00:00 2001
From: tonihei <tonihei@google.com>
Date: Mon, 23 Nov 2020 10:27:28 +0000
Subject: [PATCH] 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
---
 .../com/google/android/exoplayer2/Player.java | 42 +++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/library/core/src/main/java/com/google/android/exoplayer2/Player.java b/library/core/src/main/java/com/google/android/exoplayer2/Player.java
index 4bd60e1049..27d91c8451 100644
--- a/library/core/src/main/java/com/google/android/exoplayer2/Player.java
+++ b/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
      * {@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 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
      * 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 reason The reason for the transition.
      */
@@ -491,6 +497,9 @@ public interface Player {
     /**
      * 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 trackSelections The track selections for each renderer. Never null and always of
      *     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
      * 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.
      */
     default void onStaticMetadataChanged(List<Metadata> metadataList) {}
@@ -517,6 +529,9 @@ public interface Player {
     /**
      * 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.
      */
     @SuppressWarnings("deprecation")
@@ -538,6 +553,9 @@ public interface Player {
     /**
      * 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}.
      */
     default void onPlaybackStateChanged(@State int state) {}
@@ -545,6 +563,9 @@ public interface Player {
     /**
      * 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 reason The {@link PlayWhenReadyChangeReason reason} for the change.
      */
@@ -554,6 +575,9 @@ public interface Player {
     /**
      * 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}.
      */
     default void onPlaybackSuppressionReasonChanged(
@@ -562,6 +586,9 @@ public interface Player {
     /**
      * 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.
      */
     default void onIsPlayingChanged(boolean isPlaying) {}
@@ -569,6 +596,9 @@ public interface Player {
     /**
      * 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.
      */
     default void onRepeatModeChanged(@RepeatMode int repeatMode) {}
@@ -576,6 +606,9 @@ public interface Player {
     /**
      * 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.
      */
     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
      * #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.
      */
     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
      * 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.
      */
     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
      * 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.
      */
     default void onPlaybackParametersChanged(PlaybackParameters playbackParameters) {}