Improve MediaSource/MediaPeriod documentation

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

library/core/src/main/java/com/google/android/exoplayer2/source/MediaPeriod.java

@@ -16,12 +16,15 @@
 package com.google.android.exoplayer2.source;
 package com.google.android.exoplayer2.source;
 
 
 import com.google.android.exoplayer2.C;
 import com.google.android.exoplayer2.C;
+import com.google.android.exoplayer2.ExoPlayer;
 import com.google.android.exoplayer2.Timeline;
 import com.google.android.exoplayer2.Timeline;
 import com.google.android.exoplayer2.trackselection.TrackSelection;
 import com.google.android.exoplayer2.trackselection.TrackSelection;
 import java.io.IOException;
 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 {
 public interface MediaPeriod extends SequenceableLoader {
 
 

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;
 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 {
 public interface MediaSource {