diff --git a/library/core/src/main/java/com/google/android/exoplayer2/Timeline.java b/library/core/src/main/java/com/google/android/exoplayer2/Timeline.java
index 60650f9990..e45171fc69 100644
--- a/library/core/src/main/java/com/google/android/exoplayer2/Timeline.java
+++ b/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.
- *
- * 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.
*
* 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.
*
*
* 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 Live stream
- * with limited availability 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 Live stream with limited
+ * availability case, except that the window may span more than one period. Multiple periods are
+ * also possible in the indefinite availability case.
*
- *
On-demand pre-roll followed by live stream
+ *
On-demand stream followed by live stream
*
- *
*
* This case is the concatenation of the Single media file or on-demand
* stream and Live stream with multiple periods 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.
+ *
+ *
On-demand stream with mid-roll ads
+ *
+ *
+ *
+ * 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.
*
*
*
@@ -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.
+ *
+ * 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.
*
* 
+ * 
* 
*