Clean up MediaSessionExt documentation

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

extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/DefaultPlaybackController.java

@@ -21,40 +21,50 @@ import com.google.android.exoplayer2.C;
 import com.google.android.exoplayer2.Player;
 
 /**
- * A default implementation of the {@link MediaSessionConnector.PlaybackController}. You can safely
+ * A default implementation of {@link MediaSessionConnector.PlaybackController}.
- * override any method for instance to intercept calls for a given action.
+ * <p>
+ * Methods can be safely overridden by subclasses to intercept calls for given actions.
  */
 public class DefaultPlaybackController implements MediaSessionConnector.PlaybackController {
 
+  /**
+   * The default fast forward increment, in milliseconds.
+   */
+  public static final int DEFAULT_FAST_FORWARD_MS = 15000;
+  /**
+   * The default rewind increment, in milliseconds.
+   */
+  public static final int DEFAULT_REWIND_MS = 5000;
+
   private static final long BASE_ACTIONS = PlaybackStateCompat.ACTION_PLAY_PAUSE
       | PlaybackStateCompat.ACTION_PLAY | PlaybackStateCompat.ACTION_PAUSE
       | PlaybackStateCompat.ACTION_STOP;
 
-  protected final long fastForwardIncrementMs;
   protected final long rewindIncrementMs;
+  protected final long fastForwardIncrementMs;
 
   /**
-   * Creates a new {@link DefaultPlaybackController}. This is equivalent to calling
+   * Creates a new instance.
-   * {@code DefaultPlaybackController(15000L, 5000L)}.
+   * <p>
+   * Equivalent to {@code DefaultPlaybackController(
+   *     DefaultPlaybackController.DEFAULT_REWIND_MS,
+   *     DefaultPlaybackController.DEFAULT_FAST_FORWARD_MS)}.
    */
   public DefaultPlaybackController() {
-    this(15000L, 5000L);
+    this(DEFAULT_REWIND_MS, DEFAULT_FAST_FORWARD_MS);
   }
 
   /**
-   * Creates a new {@link DefaultPlaybackController} and sets the fast forward and rewind increments
+   * Creates a new instance with the given fast forward and rewind increments.
-   * in milliseconds.
    *
-   * @param fastForwardIncrementMs A positive value will cause the
+   * @param rewindIncrementMs The rewind increment in milliseconds. A zero or negative value will
-   *     {@link PlaybackStateCompat#ACTION_FAST_FORWARD} playback action to be added. A zero or a
+   *     cause the rewind action to be disabled.
-   *     negative value will cause it to be removed.
+   * @param fastForwardIncrementMs The fast forward increment in milliseconds. A zero or negative
-   * @param rewindIncrementMs A positive value will cause the
+   *     value will cause the fast forward action to be removed.
-   *     {@link PlaybackStateCompat#ACTION_REWIND} playback action to be added. A zero or a
-   *     negative value will cause it to be removed.
    */
-  public DefaultPlaybackController(long fastForwardIncrementMs, long rewindIncrementMs) {
+  public DefaultPlaybackController(long rewindIncrementMs, long fastForwardIncrementMs) {
-    this.fastForwardIncrementMs = fastForwardIncrementMs;
     this.rewindIncrementMs = rewindIncrementMs;
+    this.fastForwardIncrementMs = fastForwardIncrementMs;
   }
 
   @Override

extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/MediaSessionConnector.java

@@ -44,30 +44,27 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * Mediates between a {@link MediaSessionCompat} and an {@link Player} instance set with
+ * Connects a {@link MediaSessionCompat} to a {@link Player}.
- * {@link #setPlayer(Player, PlaybackPreparer, CustomActionProvider...)}.
  * <p>
- * The {@code MediaSessionConnector} listens for media actions sent by a media controller and
+ * The connector listens for actions sent by the media session's controller and implements these
- * realizes these actions by calling appropriate ExoPlayer methods. Further, the state of ExoPlayer
+ * actions by calling appropriate ExoPlayer methods. The playback state of the media session is
- * will be synced automatically with the {@link PlaybackStateCompat} of the media session to
+ * automatically synced with the player. The connector can also be optionally extended by providing
- * broadcast state transitions to clients. You can optionally extend this behaviour by providing
+ * various collaborators:
- * various collaborators.
+ * <ul>
- * <p>
+ *   <li>Actions to initiate media playback ({@code PlaybackStateCompat#ACTION_PREPARE_*} and
- * Media actions to initiate media playback ({@code PlaybackStateCompat#ACTION_PREPARE_*} and
+ *   {@code PlaybackStateCompat#ACTION_PLAY_*}) can be handled by a {@link PlaybackPreparer} passed
- * {@code PlaybackStateCompat#ACTION_PLAY_*} need to be handled by a {@link PlaybackPreparer} which
+ *   when calling {@link #setPlayer(Player, PlaybackPreparer, CustomActionProvider...)}. Custom
- * build a {@link com.google.android.exoplayer2.source.MediaSource} to prepare ExoPlayer. Deploy
+ *   actions can be handled by passing one or more {@link CustomActionProvider}s in a similar way.
- * your preparer by calling {@link #setPlaybackPreparer(PlaybackPreparer)}.
+ *   </li>
- * <p>
+ *   <li>To enable a media queue and navigation within it, you can set a {@link QueueNavigator} by
- * To support a media session queue and navigation within this queue, you can set a
+ *   calling {@link #setQueueNavigator(QueueNavigator)}. Use of {@link TimelineQueueNavigator} is
- * {@link QueueNavigator} to maintain the queue yourself and implement queue navigation commands
+ *   recommended for most use cases.</li>
- * (like 'skip to next') sent by controllers. It's recommended to use the
+ *   <li>To enable editing of the media queue, you can set a {@link QueueEditor} by calling
- * {@link TimelineQueueNavigator} to allow users navigating the windows of the ExoPlayer timeline.
+ *   {@link #setQueueEditor(QueueEditor)}.</li>
- * <p>
+ *   <li>An {@link ErrorMessageProvider} for providing human readable error messages and
- * If you want to allow media controllers to manipulate the queue, implement a {@link QueueEditor}
+ *   corresponding error codes can be set by calling
- * and deploy it with {@link #setQueueEditor(QueueEditor)}.
+ *   {@link #setErrorMessageProvider(ErrorMessageProvider)}.</li>
- * <p>
+ * </ul>
- * Set an {@link ErrorMessageProvider} to provide an error code and a human readable error message
- * to be broadcast to controllers.
  */
 public final class MediaSessionConnector {
 
@@ -78,12 +75,7 @@ public final class MediaSessionConnector {
   public static final String EXTRAS_PITCH = "EXO_PITCH";
 
   /**
-   * Interface to which media controller commands regarding preparing playback for a given media
+   * Interface to which playback preparation actions are delegated.
-   * clip are delegated to.
-   * <p>
-   * Normally preparing playback includes preparing the player with a
-   * {@link com.google.android.exoplayer2.source.MediaSource} and setting up the media session queue
-   * with a corresponding list of queue items.
    */
   public interface PlaybackPreparer {
 
@@ -131,7 +123,7 @@ public final class MediaSessionConnector {
   }
 
   /**
-   * Controller to handle playback actions.
+   * Interface to which playback actions are delegated.
    */
   public interface PlaybackController {
 
@@ -178,8 +170,8 @@ public final class MediaSessionConnector {
   }
 
   /**
-   * Navigator to handle queue navigation actions and maintain the media session queue with
+   * Handles queue navigation actions, and updates the media session queue by calling
-   * {#link MediaSessionCompat#setQueue(List)} to provide the active queue item to the connector.
+   * {@code MediaSessionCompat.setQueue()}.
    */
   public interface QueueNavigator {
 
@@ -211,7 +203,7 @@ public final class MediaSessionConnector {
      */
     void onCurrentWindowIndexChanged(Player player);
     /**
-     * Gets the id of the currently active queue item or
+     * Gets the id of the currently active queue item, or
      * {@link MediaSessionCompat.QueueItem#UNKNOWN_ID} if the active item is unknown.
      * <p>
      * To let the connector publish metadata for the active queue item, the queue item with the
@@ -241,7 +233,7 @@ public final class MediaSessionConnector {
   }
 
   /**
-   * Editor to manipulate the queue.
+   * Handles media session queue edits.
    */
   public interface QueueEditor {
 
@@ -302,12 +294,12 @@ public final class MediaSessionConnector {
   }
 
   /**
-   * Provides an user readable error code and a message for {@link ExoPlaybackException}s.
+   * Converts an exception into an error code and a user readable error message.
    */
   public interface ErrorMessageProvider {
     /**
-     * Returns a pair of an error code and a user readable error message for a given
+     * Returns a pair consisting of an error code and a user readable error message for a given
-     * {@link ExoPlaybackException}.
+     * exception.
      */
     Pair<Integer, String> getErrorMessage(ExoPlaybackException playbackException);
   }
@@ -316,6 +308,7 @@ public final class MediaSessionConnector {
    * The wrapped {@link MediaSessionCompat}.
    */
   public final MediaSessionCompat mediaSession;
+
   private final MediaControllerCompat mediaController;
   private final Handler handler;
   private final boolean doMaintainMetadata;
@@ -334,11 +327,10 @@ public final class MediaSessionConnector {
   private ExoPlaybackException playbackException;
 
   /**
-   * Creates a {@code MediaSessionConnector}. This is equivalent to calling
+   * Creates an instance. Must be called on the same thread that is used to construct the player
-   * {@code #MediaSessionConnector(mediaSession, new DefaultPlaybackController)}.
+   * instances passed to {@link #setPlayer(Player, PlaybackPreparer, CustomActionProvider...)}.
    * <p>
-   * Constructing the {@link MediaSessionConnector} needs to be done on the same thread as
+   * Equivalent to {@code MediaSessionConnector(mediaSession, new DefaultPlaybackController())}.
-   * constructing the player instance.
    *
    * @param mediaSession The {@link MediaSessionCompat} to connect to.
    */
@@ -347,14 +339,13 @@ public final class MediaSessionConnector {
   }
 
   /**
-   * Creates a {@code MediaSessionConnector}. This is equivalent to calling
+   * Creates an instance. Must be called on the same thread that is used to construct the player
-   * {@code #MediaSessionConnector(mediaSession, playbackController, true)}.
+   * instances passed to {@link #setPlayer(Player, PlaybackPreparer, CustomActionProvider...)}.
    * <p>
-   * Constructing the {@link MediaSessionConnector} needs to be done on the same thread as
+   * Equivalent to {@code MediaSessionConnector(mediaSession, playbackController, true)}.
-   * constructing the player instance.
    *
    * @param mediaSession The {@link MediaSessionCompat} to connect to.
-   * @param playbackController The {@link PlaybackController}.
+   * @param playbackController A {@link PlaybackController} for handling playback actions.
    */
   public MediaSessionConnector(MediaSessionCompat mediaSession,
       PlaybackController playbackController) {
@@ -362,19 +353,14 @@ public final class MediaSessionConnector {
   }
 
   /**
-   * Creates a {@code MediaSessionConnector} with {@link CustomActionProvider}s.
+   * Creates an instance. Must be called on the same thread that is used to construct the player
-   * <p>
+   * instances passed to {@link #setPlayer(Player, PlaybackPreparer, CustomActionProvider...)}.
-   * If you choose to pass {@code false} for {@code doMaintainMetadata} you need to maintain the
-   * metadata of the media session yourself (provide at least the duration to allow clients to show
-   * a progress bar).
-   * <p>
-   * Constructing the {@link MediaSessionConnector} needs to be done on the same thread as
-   * constructing the player instance.
    *
    * @param mediaSession The {@link MediaSessionCompat} to connect to.
-   * @param playbackController The {@link PlaybackController}.
+   * @param playbackController A {@link PlaybackController} for handling playback actions.
-   * @param doMaintainMetadata Sets whether the connector should maintain the metadata of the
+   * @param doMaintainMetadata Whether the connector should maintain the metadata of the session. If
-   *     session.
+   *     {@code false}, you need to maintain the metadata of the media session yourself (provide at
+   *     least the duration to allow clients to show a progress bar).
    */
   public MediaSessionConnector(MediaSessionCompat mediaSession,
       PlaybackController playbackController, boolean doMaintainMetadata) {
@@ -392,17 +378,14 @@ public final class MediaSessionConnector {
   }
 
   /**
-   * Sets the player to which media commands sent by a media controller are delegated.
+   * Sets the player to be connected to the media session.
-   * <p>
-   * The media session callback is set if the {@code player} is not {@code null} and the callback is
-   * removed if the {@code player} is {@code null}.
    * <p>
    * The order in which any {@link CustomActionProvider}s are passed determines the order of the
    * actions published with the playback state of the session.
    *
    * @param player The player to be connected to the {@code MediaSession}.
-   * @param playbackPreparer The playback preparer for the player.
+   * @param playbackPreparer An optional {@link PlaybackPreparer} for preparing the player.
-   * @param customActionProviders Optional {@link CustomActionProvider}s to publish and handle
+   * @param customActionProviders An optional {@link CustomActionProvider}s to publish and handle
    *     custom actions.
    */
   public void setPlayer(Player player, PlaybackPreparer playbackPreparer,
@@ -411,7 +394,7 @@ public final class MediaSessionConnector {
       this.player.removeListener(exoPlayerEventListener);
       mediaSession.setCallback(null);
     }
-    setPlaybackPreparer(playbackPreparer);
+    this.playbackPreparer = playbackPreparer;
     this.player = player;
     this.customActionProviders = (player != null && customActionProviders != null)
         ? customActionProviders : new CustomActionProvider[0];
@@ -424,9 +407,9 @@ public final class MediaSessionConnector {
   }
 
   /**
-   * Sets the optional {@link ErrorMessageProvider}.
+   * Sets the {@link ErrorMessageProvider}.
    *
-   * @param errorMessageProvider The {@link ErrorMessageProvider}.
+   * @param errorMessageProvider The error message provider.
    */
   public void setErrorMessageProvider(ErrorMessageProvider errorMessageProvider) {
     this.errorMessageProvider = errorMessageProvider;
@@ -437,25 +420,21 @@ public final class MediaSessionConnector {
    * {@code ACTION_SKIP_TO_PREVIOUS}, {@code ACTION_SKIP_TO_QUEUE_ITEM} and
    * {@code ACTION_SET_SHUFFLE_MODE_ENABLED}.
    *
-   * @param queueNavigator The navigator to handle queue navigation.
+   * @param queueNavigator The queue navigator.
    */
   public void setQueueNavigator(QueueNavigator queueNavigator) {
     this.queueNavigator = queueNavigator;
   }
 
   /**
-   * Sets the queue editor to handle commands to manipulate the queue sent by a media controller.
+   * Sets the {@link QueueEditor} to handle queue edits sent by the media controller.
    *
-   * @param queueEditor The editor to handle queue manipulation actions.
+   * @param queueEditor The queue editor.
    */
   public void setQueueEditor(QueueEditor queueEditor) {
     this.queueEditor = queueEditor;
   }
 
-  private void setPlaybackPreparer(PlaybackPreparer playbackPreparer) {
-    this.playbackPreparer = playbackPreparer;
-  }
-
   private void updateMediaSessionPlaybackState() {
     PlaybackStateCompat.Builder builder = new PlaybackStateCompat.Builder();
     if (player == null) {
@@ -603,6 +582,7 @@ public final class MediaSessionConnector {
   }
 
   private class ExoPlayerEventListener implements Player.EventListener {
+
     @Override
     public void onTimelineChanged(Timeline timeline, Object manifest) {
       if (queueNavigator != null) {

extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/RepeatModeActionProvider.java

@@ -26,10 +26,13 @@ import com.google.android.exoplayer2.util.RepeatModeUtil;
  */
 public final class RepeatModeActionProvider implements MediaSessionConnector.CustomActionProvider {
 
+  /**
+   * The default repeat toggle modes.
+   */
+  public static final @RepeatModeUtil.RepeatToggleModes int DEFAULT_REPEAT_TOGGLE_MODES =
+      RepeatModeUtil.REPEAT_TOGGLE_MODE_ONE | RepeatModeUtil.REPEAT_TOGGLE_MODE_ALL;
+
   private static final String ACTION_REPEAT_MODE = "ACTION_EXO_REPEAT_MODE";
-  @RepeatModeUtil.RepeatToggleModes
-  private static final int DEFAULT_REPEAT_MODES = RepeatModeUtil.REPEAT_TOGGLE_MODE_ONE
-      | RepeatModeUtil.REPEAT_TOGGLE_MODE_ALL;
 
   private final Player player;
   @RepeatModeUtil.RepeatToggleModes
@@ -39,20 +42,20 @@ public final class RepeatModeActionProvider implements MediaSessionConnector.Cus
   private final CharSequence repeatOffDescription;
 
   /**
-   * Creates a new {@link RepeatModeActionProvider}.
+   * Creates a new instance.
    * <p>
-   * This is equivalent to calling the two argument constructor with
+   * Equivalent to {@code RepeatModeActionProvider(context, player,
-   * {@code RepeatModeUtil#REPEAT_TOGGLE_MODE_ONE | RepeatModeUtil#REPEAT_TOGGLE_MODE_ALL}.
+   *     RepeatModeActionProvider.DEFAULT_REPEAT_TOGGLE_MODES)}.
    *
    * @param context The context.
    * @param player The player on which to toggle the repeat mode.
    */
   public RepeatModeActionProvider(Context context, Player player) {
-    this(context, player, DEFAULT_REPEAT_MODES);
+    this(context, player, DEFAULT_REPEAT_TOGGLE_MODES);
   }
 
   /**
-   * Creates a new {@link RepeatModeActionProvider} for the given repeat toggle modes.
+   * Creates a new instance enabling the given repeat toggle modes.
    *
    * @param context The context.
    * @param player The player on which to toggle the repeat mode.

extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/TimelineQueueNavigator.java

@@ -29,9 +29,8 @@ import java.util.Collections;
 import java.util.List;
 
 /**
- * An abstract implementation of the {@link MediaSessionConnector.QueueNavigator} that's based on an
+ * An abstract implementation of the {@link MediaSessionConnector.QueueNavigator} that maps the
- * {@link Player}'s current {@link Timeline} and maps the timeline of the player to the media
+ * windows of a {@link Player}'s {@link Timeline} to the media session queue.
- * session queue.
  */
 public abstract class TimelineQueueNavigator implements MediaSessionConnector.QueueNavigator {
 
@@ -44,10 +43,9 @@ public abstract class TimelineQueueNavigator implements MediaSessionConnector.Qu
   private long activeQueueItemId;
 
   /**
-   * Creates a new timeline queue navigator for a given {@link MediaSessionCompat}.
+   * Creates an instance for a given {@link MediaSessionCompat}.
    * <p>
-   * This is equivalent to calling
+   * Equivalent to {@code TimelineQueueNavigator(mediaSession, DEFAULT_MAX_QUEUE_SIZE)}.
-   * {@code #TimelineQueueNavigator(mediaSession, DEFAULT_MAX_QUEUE_SIZE)}.
    *
    * @param mediaSession The {@link MediaSessionCompat}.
    */
@@ -56,12 +54,11 @@ public abstract class TimelineQueueNavigator implements MediaSessionConnector.Qu
   }
 
   /**
-   * Creates a new timeline queue navigator for a given {@link MediaSessionCompat} and a maximum
+   * Creates an instance for a given {@link MediaSessionCompat} and maximum queue size.
-   * queue size of {@code maxQueueSize}.
    * <p>
-   * If the actual queue size is larger than {@code maxQueueSize} a floating window of
+   * If the number of windows in the {@link Player}'s {@link Timeline} exceeds {@code maxQueueSize},
-   * {@code maxQueueSize} is applied and moved back and forth when the user is navigating within the
+   * the media session queue will correspond to {@code maxQueueSize} windows centered on the one
-   * queue.
+   * currently being played.
    *
    * @param mediaSession The {@link MediaSessionCompat}.
    * @param maxQueueSize The maximum queue size.
@@ -80,12 +77,6 @@ public abstract class TimelineQueueNavigator implements MediaSessionConnector.Qu
    */
   public abstract MediaDescriptionCompat getMediaDescription(int windowIndex);
 
-  /**
-   * Supports the following media actions: {@code PlaybackStateCompat.ACTION_SKIP_TO_NEXT |
-   * PlaybackStateCompat.ACTION_SKIP_TO_PREVIOUS | PlaybackStateCompat.ACTION_SKIP_TO_QUEUE_ITEM}.
-   *
-   * @return The bit mask of the supported media actions.
-   */
   @Override
   public long getSupportedQueueNavigatorActions(Player player) {
     if (player == null || player.getCurrentTimeline().getWindowCount() < 2) {

library/ui/src/main/java/com/google/android/exoplayer2/ui/PlaybackControlView.java

@@ -249,11 +249,23 @@ public class PlaybackControlView extends FrameLayout {
 
   };
 
+  /**
+   * The default fast forward increment, in milliseconds.
+   */
   public static final int DEFAULT_FAST_FORWARD_MS = 15000;
+  /**
+   * The default rewind increment, in milliseconds.
+   */
   public static final int DEFAULT_REWIND_MS = 5000;
+  /**
+   * The default show timeout, in milliseconds.
+   */
   public static final int DEFAULT_SHOW_TIMEOUT_MS = 5000;
-  public static final @RepeatModeUtil.RepeatToggleModes int DEFAULT_REPEAT_TOGGLE_MODES
+  /**
-      = RepeatModeUtil.REPEAT_TOGGLE_MODE_NONE;
+   * The default repeat toggle modes.
+   */
+  public static final @RepeatModeUtil.RepeatToggleModes int DEFAULT_REPEAT_TOGGLE_MODES =
+      RepeatModeUtil.REPEAT_TOGGLE_MODE_NONE;
 
   /**
    * The maximum number of windows that can be shown in a multi-window time bar.