From a987e106e6a63421acb2a8eae2ae5b701df03165 Mon Sep 17 00:00:00 2001
From: tonihei <tonihei@google.com>
Date: Fri, 20 Nov 2020 17:32:56 +0000
Subject: [PATCH] Update docs with onEvents callback information.

PiperOrigin-RevId: 343507207
---
 .../java/com/google/android/exoplayer2/Player.java     |  8 +++++---
 .../exoplayer2/analytics/AnalyticsListener.java        | 10 ++++++----
 2 files changed, 11 insertions(+), 7 deletions(-)

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 1117fe65bf..4bd60e1049 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
@@ -644,13 +644,15 @@ public interface Player {
      * <p>Listeners should prefer this method over individual callbacks in the following cases:
      *
      * <ul>
-     *   <li>They intend to use multiple state values together (e.g. using {@link
-     *       #getCurrentWindowIndex()} to query in {@link #getCurrentTimeline()}).
-     *   <li>The same logic should be triggered for multiple events (e.g. when updating a UI for
+     *   <li>They intend to trigger the same logic for multiple events (e.g. when updating a UI for
      *       both {@link #onPlaybackStateChanged(int)} and {@link #onPlayWhenReadyChanged(boolean,
      *       int)}).
      *   <li>They need access to the {@link Player} object to trigger further events (e.g. to call
      *       {@link Player#seekTo(long)} after a {@link #onMediaItemTransition(MediaItem, int)}).
+     *   <li>They intend to use multiple state values together or in combination with {@link Player}
+     *       getter methods. For example using {@link #getCurrentWindowIndex()} with the {@code
+     *       timeline} provided in {@link #onTimelineChanged(Timeline, int)} is only safe from
+     *       within this method.
      *   <li>They are interested in events that logically happened together (e.g {@link
      *       #onPlaybackStateChanged(int)} to {@link #STATE_BUFFERING} because of {@link
      *       #onMediaItemTransition(MediaItem, int)}).
diff --git a/library/core/src/main/java/com/google/android/exoplayer2/analytics/AnalyticsListener.java b/library/core/src/main/java/com/google/android/exoplayer2/analytics/AnalyticsListener.java
index 3e49d422b5..fa62caa5c5 100644
--- a/library/core/src/main/java/com/google/android/exoplayer2/analytics/AnalyticsListener.java
+++ b/library/core/src/main/java/com/google/android/exoplayer2/analytics/AnalyticsListener.java
@@ -975,14 +975,16 @@ public interface AnalyticsListener {
    * <p>Listeners should prefer this method over individual callbacks in the following cases:
    *
    * <ul>
-   *   <li>They intend to use multiple state values together (e.g. using {@link
-   *       Player#getCurrentWindowIndex()} to query in {@link Player#getCurrentTimeline()}).
-   *   <li>The same logic should be triggered for multiple events (e.g. when updating a UI for both
-   *       {@link #onPlaybackStateChanged(EventTime, int)} and {@link
+   *   <li>They intend to trigger the same logic for multiple events (e.g. when updating a UI for
+   *       both {@link #onPlaybackStateChanged(EventTime, int)} and {@link
    *       #onPlayWhenReadyChanged(EventTime, boolean, int)}).
    *   <li>They need access to the {@link Player} object to trigger further events (e.g. to call
    *       {@link Player#seekTo(long)} after a {@link
    *       AnalyticsListener#onMediaItemTransition(EventTime, MediaItem, int)}).
+   *   <li>They intend to use multiple state values together or in combination with {@link Player}
+   *       getter methods. For example using {@link Player#getCurrentWindowIndex()} with the {@code
+   *       timeline} provided in {@link #onTimelineChanged(EventTime, int)} is only safe from within
+   *       this method.
    *   <li>They are interested in events that logically happened together (e.g {@link
    *       #onPlaybackStateChanged(EventTime, int)} to {@link Player#STATE_BUFFERING} because of
    *       {@link #onMediaItemTransition(EventTime, MediaItem, int)}).