Update window/period doc in Timeline.

Most users are likely to be only interested in the playlist items. So put the
Window definition first and explicitly mention that this is a playlist
item.

PiperOrigin-RevId: 263764515

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

@@ -26,96 +26,92 @@ import com.google.android.exoplayer2.util.Assertions;
  * complex compositions of media such as playlists and streams with inserted ads. Instances are
  * complex compositions of media such as playlists and streams with inserted ads. Instances are
  * immutable. For cases where media is changing dynamically (e.g. live streams), a timeline provides
  * immutable. For cases where media is changing dynamically (e.g. live streams), a timeline provides
  * a snapshot of the current state.
  * a snapshot of the current state.
- * <p>
- * A timeline consists of related {@link Period}s and {@link Window}s. A period defines a single
- * logical piece of media, for example a media file. It may also define groups of ads inserted into
- * the media, along with information about whether those ads have been loaded and played. A window
- * spans one or more periods, defining the region within those periods that's currently available
- * for playback along with additional information such as whether seeking is supported within the
- * window. Each window defines a default position, which is the position from which playback will
- * start when the player starts playing the window. The following examples illustrate timelines for
- * various use cases.
+ *
+ * <p>A timeline consists of {@link Window Windows} and {@link Period Periods}.
+ *
+ * <ul>
+ *   <li>A {@link Window} usually corresponds to one playlist item. It may span one or more periods
+ *       and it defines the region within those periods that's currently available for playback. The
+ *       window also provides additional information such as whether seeking is supported within the
+ *       window and the default position, which is the position from which playback will start when
+ *       the player starts playing the window.
+ *   <li>A {@link Period} defines a single logical piece of media, for example a media file. It may
+ *       also define groups of ads inserted into the media, along with information about whether
+ *       those ads have been loaded and played.
+ * </ul>
+ *
+ * <p>The following examples illustrate timelines for various use cases.
  *
  *
  * <h3 id="single-file">Single media file or on-demand stream</h3>
  * <h3 id="single-file">Single media file or on-demand stream</h3>
- * <p align="center">
- *   <img src="doc-files/timeline-single-file.svg" alt="Example timeline for a single file">
- * </p>
- * A timeline for a single media file or on-demand stream consists of a single period and window.
- * The window spans the whole period, indicating that all parts of the media are available for
- * playback. The window's default position is typically at the start of the period (indicated by the
- * black dot in the figure above).
+ *
+ * <p align="center"><img src="doc-files/timeline-single-file.svg" alt="Example timeline for a
+ * single file"> A timeline for a single media file or on-demand stream consists of a single period
+ * and window. The window spans the whole period, indicating that all parts of the media are
+ * available for playback. The window's default position is typically at the start of the period
+ * (indicated by the black dot in the figure above).
  *
  *
  * <h3>Playlist of media files or on-demand streams</h3>
  * <h3>Playlist of media files or on-demand streams</h3>
- * <p align="center">
- *   <img src="doc-files/timeline-playlist.svg" alt="Example timeline for a playlist of files">
- * </p>
- * A timeline for a playlist of media files or on-demand streams consists of multiple periods, each
- * with its own window. Each window spans the whole of the corresponding period, and typically has a
- * default position at the start of the period. The properties of the periods and windows (e.g.
- * their durations and whether the window is seekable) will often only become known when the player
- * starts buffering the corresponding file or stream.
+ *
+ * <p align="center"><img src="doc-files/timeline-playlist.svg" alt="Example timeline for a playlist
+ * of files"> A timeline for a playlist of media files or on-demand streams consists of multiple
+ * periods, each with its own window. Each window spans the whole of the corresponding period, and
+ * typically has a default position at the start of the period. The properties of the periods and
+ * windows (e.g. their durations and whether the window is seekable) will often only become known
+ * when the player starts buffering the corresponding file or stream.
  *
  *
  * <h3 id="live-limited">Live stream with limited availability</h3>
  * <h3 id="live-limited">Live stream with limited availability</h3>
- * <p align="center">
- *   <img src="doc-files/timeline-live-limited.svg" alt="Example timeline for a live stream with
- *       limited availability">
- * </p>
- * A timeline for a live stream consists of a period whose duration is unknown, since it's
- * continually extending as more content is broadcast. If content only remains available for a
- * limited period of time then the window may start at a non-zero position, defining the region of
- * content that can still be played. The window will have {@link Window#isDynamic} set to true if
- * the stream is still live. Its default position is typically near to the live edge (indicated by
- * the black dot in the figure above).
+ *
+ * <p align="center"><img src="doc-files/timeline-live-limited.svg" alt="Example timeline for a live
+ * stream with limited availability"> A timeline for a live stream consists of a period whose
+ * duration is unknown, since it's continually extending as more content is broadcast. If content
+ * only remains available for a limited period of time then the window may start at a non-zero
+ * position, defining the region of content that can still be played. The window will have {@link
+ * Window#isDynamic} set to true if the stream is still live. Its default position is typically near
+ * to the live edge (indicated by the black dot in the figure above).
  *
  *
  * <h3>Live stream with indefinite availability</h3>
  * <h3>Live stream with indefinite availability</h3>
- * <p align="center">
- *   <img src="doc-files/timeline-live-indefinite.svg" alt="Example timeline for a live stream with
- *       indefinite availability">
- * </p>
- * A timeline for a live stream with indefinite availability is similar to the
- * <a href="#live-limited">Live stream with limited availability</a> case, except that the window
- * starts at the beginning of the period to indicate that all of the previously broadcast content
- * can still be played.
+ *
+ * <p align="center"><img src="doc-files/timeline-live-indefinite.svg" alt="Example timeline for a
+ * live stream with indefinite availability"> A timeline for a live stream with indefinite
+ * availability is similar to the <a href="#live-limited">Live stream with limited availability</a>
+ * case, except that the window starts at the beginning of the period to indicate that all of the
+ * previously broadcast content can still be played.
  *
  *
  * <h3 id="live-multi-period">Live stream with multiple periods</h3>
  * <h3 id="live-multi-period">Live stream with multiple periods</h3>
- * <p align="center">
- *   <img src="doc-files/timeline-live-multi-period.svg" alt="Example timeline for a live stream
- *       with multiple periods">
- * </p>
- * This case arises when a live stream is explicitly divided into separate periods, for example at
- * content boundaries. This case is similar to the <a href="#live-limited">Live stream with limited
- * availability</a> case, except that the window may span more than one period. Multiple periods are
- * also possible in the indefinite availability case.
+ *
+ * <p align="center"><img src="doc-files/timeline-live-multi-period.svg" alt="Example timeline for a
+ * live stream with multiple periods"> This case arises when a live stream is explicitly divided
+ * into separate periods, for example at content boundaries. This case is similar to the <a
+ * href="#live-limited">Live stream with limited availability</a> case, except that the window may
+ * span more than one period. Multiple periods are also possible in the indefinite availability
+ * case.
  *
  *
  * <h3>On-demand stream followed by live stream</h3>
  * <h3>On-demand stream followed by live stream</h3>
- * <p align="center">
- *   <img src="doc-files/timeline-advanced.svg" alt="Example timeline for an on-demand stream
- *       followed by a live stream">
- * </p>
- * This case is the concatenation of the <a href="#single-file">Single media file or on-demand
- * stream</a> and <a href="#multi-period">Live stream with multiple periods</a> cases. When playback
- * of the on-demand stream ends, playback of the live stream will start from its default position
- * near the live edge.
+ *
+ * <p align="center"><img src="doc-files/timeline-advanced.svg" alt="Example timeline for an
+ * on-demand stream followed by a live stream"> This case is the concatenation of the <a
+ * href="#single-file">Single media file or on-demand stream</a> and <a href="#multi-period">Live
+ * stream with multiple periods</a> cases. When playback of the on-demand stream ends, playback of
+ * the live stream will start from its default position near the live edge.
  *
  *
  * <h3 id="single-file-midrolls">On-demand stream with mid-roll ads</h3>
  * <h3 id="single-file-midrolls">On-demand stream with mid-roll ads</h3>
- * <p align="center">
- *   <img src="doc-files/timeline-single-file-midrolls.svg" alt="Example timeline for an on-demand
- *       stream with mid-roll ad groups">
- * </p>
- * This case includes mid-roll ad groups, which are defined as part of the timeline's single period.
- * The period can be queried for information about the ad groups and the ads they contain.
+ *
+ * <p align="center"><img src="doc-files/timeline-single-file-midrolls.svg" alt="Example timeline
+ * for an on-demand stream with mid-roll ad groups"> This case includes mid-roll ad groups, which
+ * are defined as part of the timeline's single period. The period can be queried for information
+ * about the ad groups and the ads they contain.
  */
  */
 public abstract class Timeline {
 public abstract class Timeline {
 
 
   /**
   /**
-   * Holds information about a window in a {@link Timeline}. A window defines a region of media
-   * currently available for playback along with additional information such as whether seeking is
-   * supported within the window. The figure below shows some of the information defined by a
-   * window, as well as how this information relates to corresponding {@link Period}s in the
-   * timeline.
-   * <p align="center">
-   *   <img src="doc-files/timeline-window.svg" alt="Information defined by a timeline window">
-   * </p>
+   * Holds information about a window in a {@link Timeline}. A window usually corresponds to one
+   * playlist item and defines a region of media currently available for playback along with
+   * additional information such as whether seeking is supported within the window. The figure below
+   * shows some of the information defined by a window, as well as how this information relates to
+   * corresponding {@link Period Periods} in the timeline.
+   *
+   * <p align="center"><img src="doc-files/timeline-window.svg" alt="Information defined by a
+   * timeline window">
    */
    */
   public static final class Window {
   public static final class Window {