Update docs with onEvents callback information.

PiperOrigin-RevId: 343507207

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:
      * <p>Listeners should prefer this method over individual callbacks in the following cases:
      *
      *
      * <ul>
      * <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,
      *       both {@link #onPlaybackStateChanged(int)} and {@link #onPlayWhenReadyChanged(boolean,
      *       int)}).
      *       int)}).
      *   <li>They need access to the {@link Player} object to trigger further events (e.g. to call
      *   <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)}).
      *       {@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
      *   <li>They are interested in events that logically happened together (e.g {@link
      *       #onPlaybackStateChanged(int)} to {@link #STATE_BUFFERING} because of {@link
      *       #onPlaybackStateChanged(int)} to {@link #STATE_BUFFERING} because of {@link
      *       #onMediaItemTransition(MediaItem, int)}).
      *       #onMediaItemTransition(MediaItem, int)}).

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:
    * <p>Listeners should prefer this method over individual callbacks in the following cases:
    *
    *
    * <ul>
    * <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)}).
    *       #onPlayWhenReadyChanged(EventTime, boolean, int)}).
    *   <li>They need access to the {@link Player} object to trigger further events (e.g. to call
    *   <li>They need access to the {@link Player} object to trigger further events (e.g. to call
    *       {@link Player#seekTo(long)} after a {@link
    *       {@link Player#seekTo(long)} after a {@link
    *       AnalyticsListener#onMediaItemTransition(EventTime, MediaItem, int)}).
    *       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
    *   <li>They are interested in events that logically happened together (e.g {@link
    *       #onPlaybackStateChanged(EventTime, int)} to {@link Player#STATE_BUFFERING} because of
    *       #onPlaybackStateChanged(EventTime, int)} to {@link Player#STATE_BUFFERING} because of
    *       {@link #onMediaItemTransition(EventTime, MediaItem, int)}).
    *       {@link #onMediaItemTransition(EventTime, MediaItem, int)}).