Update Timeline Javadoc to include brief mention of ad groups

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=162601778

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

@@ -19,17 +19,20 @@ import android.util.Pair;
 import com.google.android.exoplayer2.util.Assertions;
 
 /**
- * A representation of media currently available for playback.
- * <p>
- * Timeline instances are immutable. For cases where the available media is changing dynamically
- * (e.g. live streams) a timeline provides a snapshot of the media currently available.
+ * A flexible representation of the structure of media. A timeline is able to represent the
+ * structure of a wide variety of media, from simple cases like a single media file through to
+ * 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
+ * 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. 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.
+ * 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.
  *
  * <h3 id="single-file">Single media file or on-demand stream</h3>
  * <p align="center">
@@ -78,28 +81,36 @@ import com.google.android.exoplayer2.util.Assertions;
  *       with multiple periods">
  * </p>
  * This case arises when a live stream is explicitly divided into separate periods, for example at
- * content and advert 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.
+ * 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 pre-roll 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 pre-roll
+ *   <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 pre-roll ends, playback of the live stream will start from its default position near the
- * live edge.
+ * 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">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.
  */
 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. See {@link Timeline} for more details. 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.
+   * 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>
@@ -235,9 +246,11 @@ public abstract class Timeline {
 
   /**
    * Holds information about a period in a {@link Timeline}. A period defines a single logical piece
-   * of media, for example a media file. See {@link Timeline} for more details. The figure below
-   * shows some of the information defined by a period, as well as how this information relates to a
-   * corresponding {@link Window} in the timeline.
+   * 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.
+   * <p>
+   * The figure below shows some of the information defined by a period, as well as how this
+   * information relates to a corresponding {@link Window} in the timeline.
    * <p align="center">
    *   <img src="doc-files/timeline-period.svg" alt="Information defined by a period">
    * </p>

library/core/src/main/javadoc/com/google/android/exoplayer2/doc-files/timeline-single-file-midrolls.svg

+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" version="1.1" viewBox="44 825 466 88" width="466pt" height="88pt" xmlns:dc="http://purl.org/dc/elements/1.1/">
+  <metadata> Produced by OmniGraffle 7.4 
+    <dc:date>2017-07-19 14:26:00 +0000</dc:date>
+  </metadata>
+  <defs>
+    <font-face font-family="Helvetica" font-size="10" units-per-em="1000" underline-position="-75.68359" underline-thickness="49.316406" slope="0" x-height="522.9492" cap-height="717.28516" ascent="770.0195" descent="-229.98047" font-weight="500">
+      <font-face-src>
+        <font-face-name name="Helvetica"/>
+      </font-face-src>
+    </font-face>
+    <marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="FilledArrow_Marker" viewBox="-1 -4 10 8" markerWidth="10" markerHeight="8" color="black">
+      <g>
+        <path d="M 8 0 L 0 -3 L 0 3 Z" fill="currentColor" stroke="currentColor" stroke-width="1"/>
+      </g>
+    </marker>
+  </defs>
+  <g stroke="none" stroke-opacity="1" stroke-dasharray="none" fill="none" fill-opacity="1">
+    <title>Canvas 1</title>
+    <rect fill="white" width="836" height="2e3"/>
+    <g>
+      <title>Layer 1</title>
+      <rect x="50" y="826" width="445" height="25" fill="black" fill-opacity="0"/>
+      <rect x="50" y="826" width="445" height="25" stroke="black" stroke-linecap="round" stroke-linejoin="miter" stroke-width="1"/>
+      <text transform="translate(55 832.5)" fill="black">
+        <tspan font-family="Helvetica" font-size="10" font-weight="500" x="200.82031" y="10" textLength="33.359375">period1</tspan>
+      </text>
+      <rect x="50" y="856" width="445" height="25" fill="black" fill-opacity="0"/>
+      <rect x="50" y="856" width="445" height="25" stroke="black" stroke-linecap="round" stroke-linejoin="miter" stroke-width="1"/>
+      <text transform="translate(55 862.5)" fill="black">
+        <tspan font-family="Helvetica" font-size="10" font-weight="500" x="198.04443" y="10" textLength="38.911133">window1</tspan>
+      </text>
+      <circle cx="50" cy="868.5" r="5.000008" fill="black"/>
+      <circle cx="50" cy="868.5" r="5.000008" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/>
+      <line x1="51" y1="892" x2="486.1" y2="892" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/>
+      <rect x="454.41325" y="890.4195" width="29" height="22" fill="white" fill-opacity="0"/>
+      <text transform="translate(459.41325 895.4195)" fill="black">
+        <tspan font-family="Helvetica" font-size="10" font-weight="500" x=".05419922" y="10" textLength="18.891602">time</tspan>
+      </text>
+      <rect x="139.5" y="826" width="6" height="25" fill="#ccc"/>
+      <rect x="139.5" y="826" width="6" height="25" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/>
+      <rect x="226.16667" y="826" width="6" height="25" fill="#ccc"/>
+      <rect x="226.16667" y="826" width="6" height="25" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/>
+      <rect x="312.83333" y="826" width="6" height="25" fill="#ccc"/>
+      <rect x="312.83333" y="826" width="6" height="25" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/>
+      <rect x="399.5" y="826" width="6" height="25" fill="#ccc"/>
+      <rect x="399.5" y="826" width="6" height="25" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/>
+    </g>
+  </g>
+</svg>