From d824aa9db712a57da39201829125a677c90dd925 Mon Sep 17 00:00:00 2001
From: olly <olly@google.com>
Date: Thu, 17 Aug 2017 14:19:41 -0700
Subject: [PATCH] Improve MediaSource/MediaPeriod documentation

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=165628229
---
 .../android/exoplayer2/source/MediaPeriod.java     |  5 ++++-
 .../android/exoplayer2/source/MediaSource.java     | 14 +++++++++++++-
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/library/core/src/main/java/com/google/android/exoplayer2/source/MediaPeriod.java b/library/core/src/main/java/com/google/android/exoplayer2/source/MediaPeriod.java
index 7a43dd7562..514b96ae8d 100644
--- a/library/core/src/main/java/com/google/android/exoplayer2/source/MediaPeriod.java
+++ b/library/core/src/main/java/com/google/android/exoplayer2/source/MediaPeriod.java
@@ -16,12 +16,15 @@
 package com.google.android.exoplayer2.source;
 
 import com.google.android.exoplayer2.C;
+import com.google.android.exoplayer2.ExoPlayer;
 import com.google.android.exoplayer2.Timeline;
 import com.google.android.exoplayer2.trackselection.TrackSelection;
 import java.io.IOException;
 
 /**
- * A source of a single period of media.
+ * Loads media corresponding to a {@link Timeline.Period}, and allows that media to be read. All
+ * methods are called on the player's internal playback thread, as described in the
+ * {@link ExoPlayer} Javadoc.
  */
 public interface MediaPeriod extends SequenceableLoader {
 
diff --git a/library/core/src/main/java/com/google/android/exoplayer2/source/MediaSource.java b/library/core/src/main/java/com/google/android/exoplayer2/source/MediaSource.java
index 790620a80c..11489cfbb8 100644
--- a/library/core/src/main/java/com/google/android/exoplayer2/source/MediaSource.java
+++ b/library/core/src/main/java/com/google/android/exoplayer2/source/MediaSource.java
@@ -23,7 +23,19 @@ import com.google.android.exoplayer2.upstream.Allocator;
 import java.io.IOException;
 
 /**
- * A source of media consisting of one or more {@link MediaPeriod}s.
+ * Defines and provides media to be played by an {@link ExoPlayer}. A MediaSource has two main
+ * responsibilities:
+ * <ul>
+ *   <li>To provide the player with a {@link Timeline} defining the structure of its media, and to
+ *   provide a new timeline whenever the structure of the media changes. The MediaSource provides
+ *   these timelines by calling {@link Listener#onSourceInfoRefreshed} on the {@link Listener}
+ *   passed to {@link #prepareSource(ExoPlayer, boolean, Listener)}.</li>
+ *   <li>To provide {@link MediaPeriod} instances for the periods in its timeline. MediaPeriods are
+ *   obtained by calling {@link #createPeriod(MediaPeriodId, Allocator)}, and provide a way for the
+ *   player to load and read the media.</li>
+ * </ul>
+ * All methods are called on the player's internal playback thread, as described in the
+ * {@link ExoPlayer} Javadoc.
  */
 public interface MediaSource {