Clarify MediaPeriod.readDiscontinuity Javadoc

It currently wrongly documents that it is only called before reading
streams (that has never been the case and all MediaPeriods already need
to handle calls after reading samples from the streams).

It was also a bit unclear what a discontinuity implies and the new
Javadoc calls out the main use case for discontinuties and the intended
meaning of returning a discontinuity.

#minor-release

PiperOrigin-RevId: 543989124

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/source/MediaPeriod.java

@@ -158,14 +158,18 @@ long selectTracks(
   /**
    * Attempts to read a discontinuity.
    *
+   * <p>A discontinuity implies that the provided {@link SampleStream SampleStreams} will start from
+   * a new playback position and any output pipelines need to be reset. This happens for example if
+   * the streams provide decode-only samples before the intended playback start position that need
+   * to be dropped.
+   *
    * <p>After this method has returned a value other than {@link C#TIME_UNSET}, all {@link
-   * SampleStream}s provided by the period are guaranteed to start from a key frame.
+   * SampleStream SampleStreams} provided by the period are guaranteed to start from a key frame.
    *
-   * <p>This method is only called after the period has been prepared and before reading from any
-   * {@link SampleStream}s provided by the period.
+   * <p>This method is only called after the period has been prepared.
    *
-   * @return If a discontinuity was read then the playback position in microseconds after the
-   *     discontinuity. Else {@link C#TIME_UNSET}.
+   * @return The playback position after the discontinuity, in microseconds, or {@link C#TIME_UNSET}
+   *     if there is no discontinuity.
    */
   long readDiscontinuity();