Improve Player/ExoPlayer Javadoc

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

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

@@ -18,8 +18,11 @@ package com.google.android.exoplayer2;
 import android.os.Looper;
 import android.os.Looper;
 import com.google.android.exoplayer2.audio.MediaCodecAudioRenderer;
 import com.google.android.exoplayer2.audio.MediaCodecAudioRenderer;
 import com.google.android.exoplayer2.metadata.MetadataRenderer;
 import com.google.android.exoplayer2.metadata.MetadataRenderer;
+import com.google.android.exoplayer2.source.ClippingMediaSource;
 import com.google.android.exoplayer2.source.ConcatenatingMediaSource;
 import com.google.android.exoplayer2.source.ConcatenatingMediaSource;
+import com.google.android.exoplayer2.source.DynamicConcatenatingMediaSource;
 import com.google.android.exoplayer2.source.ExtractorMediaSource;
 import com.google.android.exoplayer2.source.ExtractorMediaSource;
+import com.google.android.exoplayer2.source.LoopingMediaSource;
 import com.google.android.exoplayer2.source.MediaSource;
 import com.google.android.exoplayer2.source.MediaSource;
 import com.google.android.exoplayer2.source.MergingMediaSource;
 import com.google.android.exoplayer2.source.MergingMediaSource;
 import com.google.android.exoplayer2.source.SingleSampleMediaSource;
 import com.google.android.exoplayer2.source.SingleSampleMediaSource;
@@ -30,11 +33,10 @@ import com.google.android.exoplayer2.upstream.DataSource;
 import com.google.android.exoplayer2.video.MediaCodecVideoRenderer;
 import com.google.android.exoplayer2.video.MediaCodecVideoRenderer;
 
 
 /**
 /**
- * An extensible media player exposing traditional high-level media player functionality, such as
- * the ability to buffer media, play, pause and seek. Instances can be obtained from
+ * An extensible media player that plays {@link MediaSource}s. Instances can be obtained from
  * {@link ExoPlayerFactory}.
  * {@link ExoPlayerFactory}.
  *
  *
- * <h3>Player composition</h3>
+ * <h3>Player components</h3>
  * <p>ExoPlayer is designed to make few assumptions about (and hence impose few restrictions on) the
  * <p>ExoPlayer is designed to make few assumptions about (and hence impose few restrictions on) the
  * type of the media being played, how and where it is stored, and how it is rendered. Rather than
  * type of the media being played, how and where it is stored, and how it is rendered. Rather than
  * implementing the loading and rendering of media directly, ExoPlayer implementations delegate this
  * implementing the loading and rendering of media directly, ExoPlayer implementations delegate this
@@ -42,18 +44,20 @@ import com.google.android.exoplayer2.video.MediaCodecVideoRenderer;
  * Components common to all ExoPlayer implementations are:
  * Components common to all ExoPlayer implementations are:
  * <ul>
  * <ul>
  *   <li>A <b>{@link MediaSource}</b> that defines the media to be played, loads the media, and from
  *   <li>A <b>{@link MediaSource}</b> that defines the media to be played, loads the media, and from
- *   which the loaded media can be read. A MediaSource is injected via {@link #prepare} at the start
- *   of playback. The library modules provide default implementations for regular media files
- *   ({@link ExtractorMediaSource}), DASH (DashMediaSource), SmoothStreaming (SsMediaSource) and HLS
- *   (HlsMediaSource), implementations for merging ({@link MergingMediaSource}) and concatenating
- *   ({@link ConcatenatingMediaSource}) other MediaSources, and an implementation for loading single
- *   samples ({@link SingleSampleMediaSource}) most often used for side-loaded subtitle and closed
- *   caption files.</li>
+ *   which the loaded media can be read. A MediaSource is injected via {@link #prepare(MediaSource)}
+ *   at the start of playback. The library modules provide default implementations for regular media
+ *   files ({@link ExtractorMediaSource}), DASH (DashMediaSource), SmoothStreaming (SsMediaSource)
+ *   and HLS (HlsMediaSource), an implementation for loading single media samples
+ *   ({@link SingleSampleMediaSource}) that's most often used for side-loaded subtitle files, and
+ *   implementations for building more complex MediaSources from simpler ones
+ *   ({@link MergingMediaSource}, {@link ConcatenatingMediaSource},
+ *   {@link DynamicConcatenatingMediaSource}, {@link LoopingMediaSource} and
+ *   {@link ClippingMediaSource}).</li>
  *   <li><b>{@link Renderer}</b>s that render individual components of the media. The library
  *   <li><b>{@link Renderer}</b>s that render individual components of the media. The library
  *   provides default implementations for common media types ({@link MediaCodecVideoRenderer},
  *   provides default implementations for common media types ({@link MediaCodecVideoRenderer},
  *   {@link MediaCodecAudioRenderer}, {@link TextRenderer} and {@link MetadataRenderer}). A Renderer
  *   {@link MediaCodecAudioRenderer}, {@link TextRenderer} and {@link MetadataRenderer}). A Renderer
- *   consumes media of its corresponding type from the MediaSource being played. Renderers are
- *   injected when the player is created.</li>
+ *   consumes media from the MediaSource being played. Renderers are injected when the player is
+ *   created.</li>
  *   <li>A <b>{@link TrackSelector}</b> that selects tracks provided by the MediaSource to be
  *   <li>A <b>{@link TrackSelector}</b> that selects tracks provided by the MediaSource to be
  *   consumed by each of the available Renderers. The library provides a default implementation
  *   consumed by each of the available Renderers. The library provides a default implementation
  *   ({@link DefaultTrackSelector}) suitable for most use cases. A TrackSelector is injected when
  *   ({@link DefaultTrackSelector}) suitable for most use cases. A TrackSelector is injected when
@@ -66,14 +70,14 @@ import com.google.android.exoplayer2.video.MediaCodecVideoRenderer;
  * <p>An ExoPlayer can be built using the default components provided by the library, but may also
  * <p>An ExoPlayer can be built using the default components provided by the library, but may also
  * be built using custom implementations if non-standard behaviors are required. For example a
  * be built using custom implementations if non-standard behaviors are required. For example a
  * custom LoadControl could be injected to change the player's buffering strategy, or a custom
  * custom LoadControl could be injected to change the player's buffering strategy, or a custom
- * Renderer could be injected to use a video codec not supported natively by Android.
+ * Renderer could be injected to add support for a video codec not supported natively by Android.
  *
  *
  * <p>The concept of injecting components that implement pieces of player functionality is present
  * <p>The concept of injecting components that implement pieces of player functionality is present
  * throughout the library. The default component implementations listed above delegate work to
  * throughout the library. The default component implementations listed above delegate work to
  * further injected components. This allows many sub-components to be individually replaced with
  * further injected components. This allows many sub-components to be individually replaced with
  * custom implementations. For example the default MediaSource implementations require one or more
  * custom implementations. For example the default MediaSource implementations require one or more
  * {@link DataSource} factories to be injected via their constructors. By providing a custom factory
  * {@link DataSource} factories to be injected via their constructors. By providing a custom factory
- * it's possible to load data from a non-standard source or through a different network stack.
+ * it's possible to load data from a non-standard source, or through a different network stack.
  *
  *
  * <h3>Threading model</h3>
  * <h3>Threading model</h3>
  * <p>The figure below shows ExoPlayer's threading model.</p>
  * <p>The figure below shows ExoPlayer's threading model.</p>
@@ -99,7 +103,7 @@ import com.google.android.exoplayer2.video.MediaCodecVideoRenderer;
  * thread via a second message queue. The application thread consumes messages from the queue,
  * thread via a second message queue. The application thread consumes messages from the queue,
  * updating the application visible state and calling corresponding listener methods.</li>
  * updating the application visible state and calling corresponding listener methods.</li>
  * <li>Injected player components may use additional background threads. For example a MediaSource
  * <li>Injected player components may use additional background threads. For example a MediaSource
- * may use a background thread to load data. These are implementation specific.</li>
+ * may use background threads to load data. These are implementation specific.</li>
  * </ul>
  * </ul>
  */
  */
 public interface ExoPlayer extends Player {
 public interface ExoPlayer extends Player {

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

@@ -24,7 +24,23 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.RetentionPolicy;
 
 
 /**
 /**
- * An interface for media players.
+ * A media player interface defining traditional high-level functionality, such as the ability to
+ * play, pause, seek and query properties of the currently playing media.
+ * <p>
+ * Some important properties of media players that implement this interface are:
+ * <ul>
+ *     <li>They can provide a {@link Timeline} representing the structure of the media being played,
+ *     which can be obtained by calling {@link #getCurrentTimeline()}.</li>
+ *     <li>They can provide a {@link TrackGroupArray} defining the currently available tracks,
+ *     which can be obtained by calling {@link #getCurrentTrackGroups()}.</li>
+ *     <li>They contain a number of renderers, each of which is able to render tracks of a single
+ *     type (e.g. audio, video or text). The number of renderers and their respective track types
+ *     can be obtained by calling {@link #getRendererCount()} and {@link #getRendererType(int)}.
+ *     </li>
+ *     <li>They can provide a {@link TrackSelectionArray} defining which of the currently available
+ *     tracks are selected to be rendered by each renderer. This can be obtained by calling
+ *     {@link #getCurrentTrackSelections()}}.</li>
+ * </ul>
  */
  */
 public interface Player {
 public interface Player {
 
 
@@ -50,8 +66,8 @@ public interface Player {
      * Called when the available or selected tracks change.
      * Called when the available or selected tracks change.
      *
      *
      * @param trackGroups The available tracks. Never null, but may be of length zero.
      * @param trackGroups The available tracks. Never null, but may be of length zero.
-     * @param trackSelections The track selections for each {@link Renderer}. Never null and always
-     *     of length {@link #getRendererCount()}, but may contain null elements.
+     * @param trackSelections The track selections for each renderer. Never null and always of
+     *     length {@link #getRendererCount()}, but may contain null elements.
      */
      */
     void onTracksChanged(TrackGroupArray trackGroups, TrackSelectionArray trackSelections);
     void onTracksChanged(TrackGroupArray trackGroups, TrackSelectionArray trackSelections);
 
 
@@ -112,18 +128,17 @@ public interface Player {
   }
   }
 
 
   /**
   /**
-   * The player does not have a source to play, so it is neither buffering nor ready to play.
+   * The player does not have any media to play.
    */
    */
   int STATE_IDLE = 1;
   int STATE_IDLE = 1;
   /**
   /**
-   * The player not able to immediately play from the current position. The cause is
-   * {@link Renderer} specific, but this state typically occurs when more data needs to be
-   * loaded to be ready to play, or more data needs to be buffered for playback to resume.
+   * The player is not able to immediately play from its current position. This state typically
+   * occurs when more data needs to be loaded.
    */
    */
   int STATE_BUFFERING = 2;
   int STATE_BUFFERING = 2;
   /**
   /**
-   * The player is able to immediately play from the current position. The player will be playing if
-   * {@link #getPlayWhenReady()} returns true, and paused otherwise.
+   * The player is able to immediately play from its current position. The player will be playing if
+   * {@link #getPlayWhenReady()} is true, and paused otherwise.
    */
    */
   int STATE_READY = 3;
   int STATE_READY = 3;
   /**
   /**