Consistent Javadoc for upstream package

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

library/src/main/java/com/google/android/exoplayer2/upstream/Allocation.java

@@ -24,7 +24,7 @@ package com.google.android.exoplayer2.upstream;
 public final class Allocation {
 public final class Allocation {
 
 
   /**
   /**
-   * The array containing the allocated space. The allocated space may not be at the start of the
+   * The array containing the allocated space. The allocated space might not be at the start of the
    * array, and so {@link #translateOffset(int)} method must be used when indexing into it.
    * array, and so {@link #translateOffset(int)} method must be used when indexing into it.
    */
    */
   public final byte[] data;
   public final byte[] data;

library/src/main/java/com/google/android/exoplayer2/upstream/Allocator.java

@@ -31,22 +31,22 @@ public interface Allocator {
   Allocation allocate();
   Allocation allocate();
 
 
   /**
   /**
-   * Return an {@link Allocation}.
+   * Releases an {@link Allocation} back to the allocator.
    *
    *
-   * @param allocation The {@link Allocation} being returned.
+   * @param allocation The {@link Allocation} being released.
    */
    */
   void release(Allocation allocation);
   void release(Allocation allocation);
 
 
   /**
   /**
-   * Return an array of {@link Allocation}s.
+   * Releases an array of {@link Allocation}s back to the allocator.
    *
    *
-   * @param allocations The array of {@link Allocation}s being returned.
+   * @param allocations The array of {@link Allocation}s being released.
    */
    */
   void release(Allocation[] allocations);
   void release(Allocation[] allocations);
 
 
   /**
   /**
-   * Hints to the {@link Allocator} that it should make a best effort to release any memory that it
-   * has allocated beyond the target buffer size.
+   * Hints to the allocator that it should make a best effort to release any excess
+   * {@link Allocation}s.
    */
    */
   void trim();
   void trim();
 
 

library/src/main/java/com/google/android/exoplayer2/upstream/AssetDataSource.java

@@ -26,7 +26,7 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.io.InputStream;
 
 
 /**
 /**
- * A local asset {@link DataSource}.
+ * A {@link DataSource} for reading from a local asset.
  */
  */
 public final class AssetDataSource implements DataSource {
 public final class AssetDataSource implements DataSource {
 
 
@@ -50,16 +50,15 @@ public final class AssetDataSource implements DataSource {
   private boolean opened;
   private boolean opened;
 
 
   /**
   /**
-   * Constructs a new {@link DataSource} that retrieves data from a local asset.
+   * @param context A context.
    */
    */
   public AssetDataSource(Context context) {
   public AssetDataSource(Context context) {
     this(context, null);
     this(context, null);
   }
   }
 
 
   /**
   /**
-   * Constructs a new {@link DataSource} that retrieves data from a local asset.
-   *
-   * @param listener An optional listener. Specify {@code null} for no listener.
+   * @param context A context.
+   * @param listener An optional listener.
    */
    */
   public AssetDataSource(Context context, TransferListener listener) {
   public AssetDataSource(Context context, TransferListener listener) {
     this.assetManager = context.getAssets();
     this.assetManager = context.getAssets();

library/src/main/java/com/google/android/exoplayer2/upstream/BandwidthMeter.java

@@ -21,20 +21,23 @@ package com.google.android.exoplayer2.upstream;
 public interface BandwidthMeter {
 public interface BandwidthMeter {
 
 
   /**
   /**
-   * Interface definition for a callback to be notified of {@link BandwidthMeter} events.
+   * A listener of {@link BandwidthMeter} events.
    */
    */
   interface EventListener {
   interface EventListener {
 
 
     /**
     /**
      * Invoked periodically to indicate that bytes have been transferred.
      * Invoked periodically to indicate that bytes have been transferred.
+     * <p>
+     * Note: The estimated bitrate is typically derived from more information than just
+     * {@code bytes} and {@code elapsedMs}.
      *
      *
      * @param elapsedMs The time taken to transfer the bytes, in milliseconds.
      * @param elapsedMs The time taken to transfer the bytes, in milliseconds.
      * @param bytes The number of bytes transferred.
      * @param bytes The number of bytes transferred.
-     * @param bitrate The estimated bitrate in bits/sec, or {@link #NO_ESTIMATE} if no estimate
-     *     is available. Note that this estimate is typically derived from more information than
-     *     {@code bytes} and {@code elapsedMs}.
+     * @param bitrate The estimated bitrate in bits/sec, or {@link #NO_ESTIMATE} if an estimate is
+     *     not available.
      */
      */
     void onBandwidthSample(int elapsedMs, long bytes, long bitrate);
     void onBandwidthSample(int elapsedMs, long bytes, long bitrate);
+
   }
   }
 
 
   /**
   /**
@@ -43,9 +46,8 @@ public interface BandwidthMeter {
   long NO_ESTIMATE = -1;
   long NO_ESTIMATE = -1;
 
 
   /**
   /**
-   * Gets the estimated bandwidth, in bits/sec.
-   *
-   * @return Estimated bandwidth in bits/sec, or {@link #NO_ESTIMATE} if no estimate is available.
+   * Returns the estimated bandwidth in bits/sec, or {@link #NO_ESTIMATE} if an estimate is not
+   * available.
    */
    */
   long getBitrateEstimate();
   long getBitrateEstimate();
 
 

library/src/main/java/com/google/android/exoplayer2/upstream/ByteArrayDataSink.java

@@ -29,14 +29,13 @@ public final class ByteArrayDataSink implements DataSink {
   private ByteArrayOutputStream stream;
   private ByteArrayOutputStream stream;
 
 
   @Override
   @Override
-  public DataSink open(DataSpec dataSpec) throws IOException {
+  public void open(DataSpec dataSpec) throws IOException {
     if (dataSpec.length == C.LENGTH_UNBOUNDED) {
     if (dataSpec.length == C.LENGTH_UNBOUNDED) {
       stream = new ByteArrayOutputStream();
       stream = new ByteArrayOutputStream();
     } else {
     } else {
       Assertions.checkArgument(dataSpec.length <= Integer.MAX_VALUE);
       Assertions.checkArgument(dataSpec.length <= Integer.MAX_VALUE);
       stream = new ByteArrayOutputStream((int) dataSpec.length);
       stream = new ByteArrayOutputStream((int) dataSpec.length);
     }
     }
-    return this;
   }
   }
 
 
   @Override
   @Override
@@ -50,9 +49,8 @@ public final class ByteArrayDataSink implements DataSink {
   }
   }
 
 
   /**
   /**
-   * Returns the data written to the sink since the last call to {@link #open(DataSpec)}.
-   *
-   * @return The data, or null if {@link #open(DataSpec)} has never been called.
+   * Returns the data written to the sink since the last call to {@link #open(DataSpec)}, or null if
+   * {@link #open(DataSpec)} has never been called.
    */
    */
   public byte[] getData() {
   public byte[] getData() {
     return stream == null ? null : stream.toByteArray();
     return stream == null ? null : stream.toByteArray();

library/src/main/java/com/google/android/exoplayer2/upstream/ByteArrayDataSource.java

@@ -78,4 +78,3 @@ public final class ByteArrayDataSource implements DataSource {
   }
   }
 
 
 }
 }
-

library/src/main/java/com/google/android/exoplayer2/upstream/ContentDataSource.java

@@ -28,7 +28,7 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.io.InputStream;
 
 
 /**
 /**
- * A content URI {@link DataSource}.
+ * A {@link DataSource} for reading from a content URI.
  */
  */
 public final class ContentDataSource implements DataSource {
 public final class ContentDataSource implements DataSource {
 
 
@@ -52,16 +52,15 @@ public final class ContentDataSource implements DataSource {
   private boolean opened;
   private boolean opened;
 
 
   /**
   /**
-   * Constructs a new {@link DataSource} that retrieves data from a content provider.
+   * @param context A context.
    */
    */
   public ContentDataSource(Context context) {
   public ContentDataSource(Context context) {
     this(context, null);
     this(context, null);
   }
   }
 
 
   /**
   /**
-   * Constructs a new {@link DataSource} that retrieves data from a content provider.
-   *
-   * @param listener An optional listener. Specify {@code null} for no listener.
+   * @param context A context.
+   * @param listener An optional listener.
    */
    */
   public ContentDataSource(Context context, TransferListener listener) {
   public ContentDataSource(Context context, TransferListener listener) {
     this.resolver = context.getContentResolver();
     this.resolver = context.getContentResolver();

library/src/main/java/com/google/android/exoplayer2/upstream/DataSink.java

@@ -18,25 +18,17 @@ package com.google.android.exoplayer2.upstream;
 import java.io.IOException;
 import java.io.IOException;
 
 
 /**
 /**
- * A component that consumes media data.
+ * A component to which streams of data can be written.
  */
  */
 public interface DataSink {
 public interface DataSink {
 
 
   /**
   /**
-   * Opens the {@link DataSink} to consume the specified data.
+   * Opens the sink to consume the specified data.
    *
    *
    * @param dataSpec Defines the data to be consumed.
    * @param dataSpec Defines the data to be consumed.
-   * @return This {@link DataSink}, for convenience.
-   * @throws IOException
+   * @throws IOException If an error occurs opening the sink.
    */
    */
-  DataSink open(DataSpec dataSpec) throws IOException;
-
-  /**
-   * Closes the {@link DataSink}.
-   *
-   * @throws IOException
-   */
-  void close() throws IOException;
+  void open(DataSpec dataSpec) throws IOException;
 
 
   /**
   /**
    * Consumes the provided data.
    * Consumes the provided data.
@@ -44,8 +36,15 @@ public interface DataSink {
    * @param buffer The buffer from which data should be consumed.
    * @param buffer The buffer from which data should be consumed.
    * @param offset The offset of the data to consume in {@code buffer}.
    * @param offset The offset of the data to consume in {@code buffer}.
    * @param length The length of the data to consume, in bytes.
    * @param length The length of the data to consume, in bytes.
-   * @throws IOException
+   * @throws IOException If an error occurs writing to the sink.
    */
    */
   void write(byte[] buffer, int offset, int length) throws IOException;
   void write(byte[] buffer, int offset, int length) throws IOException;
 
 
+  /**
+   * Closes the sink.
+   *
+   * @throws IOException If an error occurs closing the sink.
+   */
+  void close() throws IOException;
+
 }
 }

library/src/main/java/com/google/android/exoplayer2/upstream/DataSource.java

@@ -22,7 +22,7 @@ import android.net.Uri;
 import java.io.IOException;
 import java.io.IOException;
 
 
 /**
 /**
- * A component that provides media data.
+ * A component from which streams of data can be read.
  */
  */
 public interface DataSource {
 public interface DataSource {
 
 
@@ -39,11 +39,10 @@ public interface DataSource {
   }
   }
 
 
   /**
   /**
-   * Opens the {@link DataSource} to read the specified data.
+   * Opens the source to read the specified data.
    * <p>
    * <p>
    * Note: If an {@link IOException} is thrown, callers must still call {@link #close()} to ensure
    * Note: If an {@link IOException} is thrown, callers must still call {@link #close()} to ensure
-   * that any partial effects of the invocation are cleaned up. Implementations of this class can
-   * assume that callers will call {@link #close()} in this case.
+   * that any partial effects of the invocation are cleaned up.
    *
    *
    * @param dataSpec Defines the data to be read.
    * @param dataSpec Defines the data to be read.
    * @throws IOException If an error occurs opening the source.
    * @throws IOException If an error occurs opening the source.
@@ -57,10 +56,8 @@ public interface DataSource {
 
 
   /**
   /**
    * Reads up to {@code length} bytes of data and stores them into {@code buffer}, starting at
    * Reads up to {@code length} bytes of data and stores them into {@code buffer}, starting at
-   * index {@code offset}.
-   * <p>
-   * This method blocks until at least one byte of data can be read, the end of the opened range is
-   * detected, or an exception is thrown.
+   * index {@code offset}. Blocks until at least one byte of data can be read, the end of the opened
+   * range is detected, or an exception is thrown.
    *
    *
    * @param buffer The buffer into which the read data should be stored.
    * @param buffer The buffer into which the read data should be stored.
    * @param offset The start offset into {@code buffer} at which data should be written.
    * @param offset The start offset into {@code buffer} at which data should be written.
@@ -72,20 +69,19 @@ public interface DataSource {
   int read(byte[] buffer, int offset, int readLength) throws IOException;
   int read(byte[] buffer, int offset, int readLength) throws IOException;
 
 
   /**
   /**
-   * When the source is open, returns the {@link Uri} from which data is being read.
-   * <p>
-   * The returned {@link Uri} will be identical to the one passed {@link #open(DataSpec)} in the
-   * {@link DataSpec} unless redirection has occurred. If redirection has occurred, the {@link Uri}
-   * after redirection is returned.
+   * When the source is open, returns the {@link Uri} from which data is being read. The returned
+   * {@link Uri} will be identical to the one passed {@link #open(DataSpec)} in the {@link DataSpec}
+   * unless redirection has occurred. If redirection has occurred, the {@link Uri} after redirection
+   * is returned.
    *
    *
-   * @return When the source is open, the {@link Uri} from which data is being read. Null otherwise.
+   * @return The {@link Uri} from which data is being read, or null if the source is not open.
    */
    */
   Uri getUri();
   Uri getUri();
 
 
   /**
   /**
-   * Closes the {@link DataSource}.
+   * Closes the source.
    * <p>
    * <p>
-   * Note: This method will be called even if the corresponding call to {@link #open(DataSpec)}
+   * Note: This method must be called even if the corresponding call to {@link #open(DataSpec)}
    * threw an {@link IOException}. See {@link #open(DataSpec)} for more details.
    * threw an {@link IOException}. See {@link #open(DataSpec)} for more details.
    *
    *
    * @throws IOException If an error occurs closing the source.
    * @throws IOException If an error occurs closing the source.

library/src/main/java/com/google/android/exoplayer2/upstream/DataSourceInputStream.java

@@ -23,7 +23,7 @@ import java.io.InputStream;
 
 
 /**
 /**
  * Allows data corresponding to a given {@link DataSpec} to be read from a {@link DataSource} and
  * Allows data corresponding to a given {@link DataSpec} to be read from a {@link DataSource} and
- * consumed as an {@link InputStream}.
+ * consumed through an {@link InputStream}.
  */
  */
 public final class DataSourceInputStream extends InputStream {
 public final class DataSourceInputStream extends InputStream {
 
 

library/src/main/java/com/google/android/exoplayer2/upstream/DataSpec.java

@@ -23,7 +23,7 @@ import android.net.Uri;
 import java.util.Arrays;
 import java.util.Arrays;
 
 
 /**
 /**
- * Defines a region of media data.
+ * Defines a region of data.
  */
  */
 public final class DataSpec {
 public final class DataSpec {
 
 
@@ -41,7 +41,7 @@ public final class DataSpec {
   public static final int FLAG_ALLOW_GZIP = 1;
   public static final int FLAG_ALLOW_GZIP = 1;
 
 
   /**
   /**
-   * Identifies the source from which data should be read.
+   * The source from which data should be read.
    */
    */
   public final Uri uri;
   public final Uri uri;
   /**
   /**

library/src/main/java/com/google/android/exoplayer2/upstream/DefaultAllocator.java

@@ -37,20 +37,20 @@ public final class DefaultAllocator implements Allocator {
   private Allocation[] availableAllocations;
   private Allocation[] availableAllocations;
 
 
   /**
   /**
-   * Constructs an initially empty pool.
+   * Constructs an instance without creating any {@link Allocation}s up front.
    *
    *
-   * @param individualAllocationSize The length of each individual allocation.
+   * @param individualAllocationSize The length of each individual {@link Allocation}.
    */
    */
   public DefaultAllocator(int individualAllocationSize) {
   public DefaultAllocator(int individualAllocationSize) {
     this(individualAllocationSize, 0);
     this(individualAllocationSize, 0);
   }
   }
 
 
   /**
   /**
-   * Constructs a pool with some {@link Allocation}s created up front.
+   * Constructs an instance with some {@link Allocation}s created up front.
    * <p>
    * <p>
-   * Note: Initial {@link Allocation}s will never be discarded by {@link #trim()}.
+   * Note: {@link Allocation}s created up front will never be discarded by {@link #trim()}.
    *
    *
-   * @param individualAllocationSize The length of each individual allocation.
+   * @param individualAllocationSize The length of each individual {@link Allocation}.
    * @param initialAllocationCount The number of allocations to create up front.
    * @param initialAllocationCount The number of allocations to create up front.
    */
    */
   public DefaultAllocator(int individualAllocationSize, int initialAllocationCount) {
   public DefaultAllocator(int individualAllocationSize, int initialAllocationCount) {

library/src/main/java/com/google/android/exoplayer2/upstream/DefaultBandwidthMeter.java

@@ -22,11 +22,14 @@ import android.os.Handler;
 import android.os.SystemClock;
 import android.os.SystemClock;
 
 
 /**
 /**
- * Counts transferred bytes while transfers are open and creates a bandwidth sample and updated
- * bandwidth estimate each time a transfer ends.
+ * Estimates bandwidth by listening to data transfers. The bandwidth estimate is calculated using
+ * a {@link SlidingPercentile} and is updated each time a transfer ends.
  */
  */
 public final class DefaultBandwidthMeter implements BandwidthMeter, TransferListener {
 public final class DefaultBandwidthMeter implements BandwidthMeter, TransferListener {
 
 
+  /**
+   * The default maximum weight for the sliding window.
+   */
   public static final int DEFAULT_MAX_WEIGHT = 2000;
   public static final int DEFAULT_MAX_WEIGHT = 2000;
 
 
   private static final int ELAPSED_MILLIS_FOR_ESTIMATE = 2000;
   private static final int ELAPSED_MILLIS_FOR_ESTIMATE = 2000;

library/src/main/java/com/google/android/exoplayer2/upstream/DefaultDataSource.java

@@ -54,7 +54,7 @@ public final class DefaultDataSource implements DataSource {
    * Constructs a new instance, optionally configured to follow cross-protocol redirects.
    * Constructs a new instance, optionally configured to follow cross-protocol redirects.
    *
    *
    * @param context A context.
    * @param context A context.
-   * @param listener An optional {@link TransferListener}.
+   * @param listener An optional listener.
    * @param userAgent The User-Agent string that should be used when requesting remote data.
    * @param userAgent The User-Agent string that should be used when requesting remote data.
    * @param allowCrossProtocolRedirects Whether cross-protocol redirects (i.e. redirects from HTTP
    * @param allowCrossProtocolRedirects Whether cross-protocol redirects (i.e. redirects from HTTP
    *     to HTTPS and vice versa) are enabled when fetching remote data..
    *     to HTTPS and vice versa) are enabled when fetching remote data..
@@ -72,7 +72,7 @@ public final class DefaultDataSource implements DataSource {
    * than file, asset and content.
    * than file, asset and content.
    *
    *
    * @param context A context.
    * @param context A context.
-   * @param listener An optional {@link TransferListener}.
+   * @param listener An optional listener.
    * @param baseDataSource A {@link DataSource} to use for URI schemes other than file, asset and
    * @param baseDataSource A {@link DataSource} to use for URI schemes other than file, asset and
    *     content. This {@link DataSource} should normally support at least http(s).
    *     content. This {@link DataSource} should normally support at least http(s).
    */
    */

library/src/main/java/com/google/android/exoplayer2/upstream/DefaultDataSourceFactory.java

@@ -27,29 +27,44 @@ public final class DefaultDataSourceFactory implements Factory {
 
 
   private final Context context;
   private final Context context;
   private final String userAgent;
   private final String userAgent;
-  private final TransferListener transferListener;
+  private final TransferListener listener;
   private final boolean allowCrossProtocolRedirects;
   private final boolean allowCrossProtocolRedirects;
 
 
+  /**
+   * @param context A context.
+   * @param userAgent The User-Agent string that should be used.
+   */
   public DefaultDataSourceFactory(Context context, String userAgent) {
   public DefaultDataSourceFactory(Context context, String userAgent) {
     this(context, userAgent, null);
     this(context, userAgent, null);
   }
   }
 
 
-  public DefaultDataSourceFactory(Context context, String userAgent,
-      TransferListener transferListener) {
-    this(context, userAgent, transferListener, false);
+  /**
+   * @param context A context.
+   * @param userAgent The User-Agent string that should be used.
+   * @param listener An optional listener.
+   */
+  public DefaultDataSourceFactory(Context context, String userAgent, TransferListener listener) {
+    this(context, userAgent, listener, false);
   }
   }
 
 
-  public DefaultDataSourceFactory(Context context, String userAgent,
-      TransferListener transferListener, boolean allowCrossProtocolRedirects) {
+  /**
+   * @param context A context.
+   * @param userAgent The User-Agent string that should be used.
+   * @param listener An optional listener.
+   * @param allowCrossProtocolRedirects Whether cross-protocol redirects (i.e. redirects from HTTP
+   *     to HTTPS and vice versa) are enabled.
+   */
+  public DefaultDataSourceFactory(Context context, String userAgent, TransferListener listener,
+      boolean allowCrossProtocolRedirects) {
     this.context = context.getApplicationContext();
     this.context = context.getApplicationContext();
     this.userAgent = userAgent;
     this.userAgent = userAgent;
-    this.transferListener = transferListener;
+    this.listener = listener;
     this.allowCrossProtocolRedirects = allowCrossProtocolRedirects;
     this.allowCrossProtocolRedirects = allowCrossProtocolRedirects;
   }
   }
 
 
   @Override
   @Override
   public DefaultDataSource createDataSource() {
   public DefaultDataSource createDataSource() {
-    return new DefaultDataSource(context, transferListener, userAgent, allowCrossProtocolRedirects);
+    return new DefaultDataSource(context, listener, userAgent, allowCrossProtocolRedirects);
   }
   }
 
 
 }
 }

library/src/main/java/com/google/android/exoplayer2/upstream/DefaultHttpDataSource.java

@@ -42,7 +42,7 @@ import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import java.util.regex.Pattern;
 
 
 /**
 /**
- * A {@link HttpDataSource} that uses Android's {@link HttpURLConnection}.
+ * An {@link HttpDataSource} that uses Android's {@link HttpURLConnection}.
  * <p>
  * <p>
  * By default this implementation will not follow cross-protocol redirects (i.e. redirects from
  * By default this implementation will not follow cross-protocol redirects (i.e. redirects from
  * HTTP to HTTPS or vice versa). Cross-protocol redirects can be enabled by using the
  * HTTP to HTTPS or vice versa). Cross-protocol redirects can be enabled by using the

library/src/main/java/com/google/android/exoplayer2/upstream/FileDataSource.java

@@ -24,7 +24,7 @@ import java.io.IOException;
 import java.io.RandomAccessFile;
 import java.io.RandomAccessFile;
 
 
 /**
 /**
- * A local file {@link DataSource}.
+ * A {@link DataSource} for reading local files.
  */
  */
 public final class FileDataSource implements DataSource {
 public final class FileDataSource implements DataSource {
 
 
@@ -46,17 +46,12 @@ public final class FileDataSource implements DataSource {
   private long bytesRemaining;
   private long bytesRemaining;
   private boolean opened;
   private boolean opened;
 
 
-  /**
-   * Constructs a new {@link DataSource} that retrieves data from a file.
-   */
   public FileDataSource() {
   public FileDataSource() {
     this(null);
     this(null);
   }
   }
 
 
   /**
   /**
-   * Constructs a new {@link DataSource} that retrieves data from a file.
-   *
-   * @param listener An optional listener. Specify {@code null} for no listener.
+   * @param listener An optional listener.
    */
    */
   public FileDataSource(TransferListener listener) {
   public FileDataSource(TransferListener listener) {
     this.listener = listener;
     this.listener = listener;

library/src/main/java/com/google/android/exoplayer2/upstream/HttpDataSource.java

@@ -25,7 +25,7 @@ import java.util.List;
 import java.util.Map;
 import java.util.Map;
 
 
 /**
 /**
- * An HTTP specific extension to {@link DataSource}.
+ * An HTTP {@link DataSource}.
  */
  */
 public interface HttpDataSource extends DataSource {
 public interface HttpDataSource extends DataSource {
 
 
@@ -166,9 +166,8 @@ public interface HttpDataSource extends DataSource {
   void clearAllRequestProperties();
   void clearAllRequestProperties();
 
 
   /**
   /**
-   * Gets the headers provided in the response.
-   *
-   * @return The response headers, or {@code null} if response headers are unavailable.
+   * Returns the headers provided in the response, or {@code null} if response headers are
+   * unavailable.
    */
    */
   Map<String, List<String>> getResponseHeaders();
   Map<String, List<String>> getResponseHeaders();
 
 

library/src/main/java/com/google/android/exoplayer2/upstream/Loader.java

@@ -56,14 +56,12 @@ public final class Loader {
     void cancelLoad();
     void cancelLoad();
 
 
     /**
     /**
-     * Whether the load has been canceled.
-     *
-     * @return True if the load has been canceled. False otherwise.
+     * Returns whether the load has been canceled.
      */
      */
     boolean isLoadCanceled();
     boolean isLoadCanceled();
 
 
     /**
     /**
-     * Performs the load, returning on completion or cancelation.
+     * Performs the load, returning on completion or cancellation.
      *
      *
      * @throws IOException
      * @throws IOException
      * @throws InterruptedException
      * @throws InterruptedException
@@ -78,10 +76,10 @@ public final class Loader {
   public interface Callback<T extends Loadable> {
   public interface Callback<T extends Loadable> {
 
 
     /**
     /**
-     * Invoked when a load has completed.
+     * Called when a load has completed.
      * <p>
      * <p>
-     * There is guaranteed to exist a memory barrier between {@link Loadable#load()} exiting and
-     * this callback being invoked.
+     * Note: There is guaranteed to be a memory barrier between {@link Loadable#load()} exiting and
+     * this callback being called.
      *
      *
      * @param loadable The loadable whose load has completed.
      * @param loadable The loadable whose load has completed.
      * @param elapsedRealtimeMs {@link SystemClock#elapsedRealtime} when the load ended.
      * @param elapsedRealtimeMs {@link SystemClock#elapsedRealtime} when the load ended.
@@ -90,11 +88,11 @@ public final class Loader {
     void onLoadCompleted(T loadable, long elapsedRealtimeMs, long loadDurationMs);
     void onLoadCompleted(T loadable, long elapsedRealtimeMs, long loadDurationMs);
 
 
     /**
     /**
-     * Invoked when a load has been canceled.
+     * Called when a load has been canceled.
      * <p>
      * <p>
-     * If the {@link Loader} has not been released then there is guaranteed to exist a memory
-     * barrier between {@link Loadable#load()} exiting and this callback being invoked. If the
-     * {@link Loader} has been released then this callback may be invoked before
+     * Note: If the {@link Loader} has not been released then there is guaranteed to be a memory
+     * barrier between {@link Loadable#load()} exiting and this callback being called. If the
+     * {@link Loader} has been released then this callback may be called before
      * {@link Loadable#load()} exits.
      * {@link Loadable#load()} exits.
      *
      *
      * @param loadable The loadable whose load has been canceled.
      * @param loadable The loadable whose load has been canceled.
@@ -106,10 +104,10 @@ public final class Loader {
     void onLoadCanceled(T loadable, long elapsedRealtimeMs, long loadDurationMs, boolean released);
     void onLoadCanceled(T loadable, long elapsedRealtimeMs, long loadDurationMs, boolean released);
 
 
     /**
     /**
-     * Invoked when a load encounters an error.
+     * Called when a load encounters an error.
      * <p>
      * <p>
-     * There is guaranteed to exist a memory barrier between {@link Loadable#load()} exiting and
-     * this callback being invoked.
+     * Note: There is guaranteed to be a memory barrier between {@link Loadable#load()} exiting and
+     * this callback being called.
      *
      *
      * @param loadable The loadable whose load has encountered an error.
      * @param loadable The loadable whose load has encountered an error.
      * @param elapsedRealtimeMs {@link SystemClock#elapsedRealtime} when the error occurred.
      * @param elapsedRealtimeMs {@link SystemClock#elapsedRealtime} when the error occurred.
@@ -147,13 +145,13 @@ public final class Loader {
   }
   }
 
 
   /**
   /**
-   * Start loading a {@link Loadable}.
+   * Starts loading a {@link Loadable}.
    * <p>
    * <p>
    * The calling thread must be a {@link Looper} thread, which is the thread on which the
    * The calling thread must be a {@link Looper} thread, which is the thread on which the
-   * {@link Callback} will be invoked.
+   * {@link Callback} will be called.
    *
    *
    * @param loadable The {@link Loadable} to load.
    * @param loadable The {@link Loadable} to load.
-   * @param callback A callback to invoke when the load ends.
+   * @param callback A callback to called when the load ends.
    * @param defaultMinRetryCount The minimum number of times the load must be retried before
    * @param defaultMinRetryCount The minimum number of times the load must be retried before
    *     {@link #maybeThrowError()} will propagate an error.
    *     {@link #maybeThrowError()} will propagate an error.
    * @throws IllegalStateException If the calling thread does not have an associated {@link Looper}.
    * @throws IllegalStateException If the calling thread does not have an associated {@link Looper}.
@@ -169,18 +167,16 @@ public final class Loader {
   }
   }
 
 
   /**
   /**
-   * Whether the {@link Loader} is currently loading a {@link Loadable}.
-   *
-   * @return Whether the {@link Loader} is currently loading a {@link Loadable}.
+   * Returns whether the {@link Loader} is currently loading a {@link Loadable}.
    */
    */
   public boolean isLoading() {
   public boolean isLoading() {
     return currentTask != null;
     return currentTask != null;
   }
   }
 
 
   /**
   /**
-   * If a fatal error has been encountered, or if the current {@link Loadable} has incurred a number
-   * of errors greater than its default minimum number of retries and if the load is currently
-   * backed off, then an error is thrown. Else does nothing.
+   * Throws an error if a fatal error has been encountered, or if the current {@link Loadable} has
+   * incurred a number of errors greater than its default minimum number of retries and if the load
+   * is currently backed off, then an error is thrown. Else does nothing.
    *
    *
    * @throws IOException The error.
    * @throws IOException The error.
    */
    */
@@ -189,9 +185,9 @@ public final class Loader {
   }
   }
 
 
   /**
   /**
-   * If a fatal error has been encountered, or if the current {@link Loadable} has incurred a number
-   * of errors greater than the specified minimum number of retries and if the load is currently
-   * backed off, then an error is thrown. Else does nothing.
+   * Throws an error if a fatal error has been encountered, or if the current {@link Loadable} has
+   * incurred a number of errors greater than the specified minimum number of retries and if the
+   * load is currently backed off, then an error is thrown.
    *
    *
    * @param minRetryCount A minimum retry count that must be exceeded.
    * @param minRetryCount A minimum retry count that must be exceeded.
    * @throws IOException The error.
    * @throws IOException The error.
@@ -206,27 +202,23 @@ public final class Loader {
   }
   }
 
 
   /**
   /**
-   * Cancels the current load.
-   * <p>
-   * This method should only be called when a load is in progress.
+   * Cancels the current load. This method should only be called when a load is in progress.
    */
    */
   public void cancelLoading() {
   public void cancelLoading() {
     currentTask.cancel(false);
     currentTask.cancel(false);
   }
   }
 
 
   /**
   /**
-   * Releases the {@link Loader}.
-   * <p>
-   * This method should be called when the {@link Loader} is no longer required.
+   * Releases the {@link Loader}. This method should be called when the {@link Loader} is no longer
+   * required.
    */
    */
   public void release() {
   public void release() {
     release(null);
     release(null);
   }
   }
 
 
   /**
   /**
-   * Releases the {@link Loader}, running {@code postLoadAction} on its thread.
-   * <p>
-   * This method should be called when the {@link Loader} is no longer required.
+   * Releases the {@link Loader}, running {@code postLoadAction} on its thread. This method should
+   * be called when the {@link Loader} is no longer required.
    *
    *
    * @param postLoadAction A {@link Runnable} to run on the loader's thread when
    * @param postLoadAction A {@link Runnable} to run on the loader's thread when
    *     {@link Loadable#load()} is no longer running.
    *     {@link Loadable#load()} is no longer running.

library/src/main/java/com/google/android/exoplayer2/upstream/ParsingLoadable.java

@@ -39,7 +39,7 @@ public final class ParsingLoadable<T> implements Loadable {
     /**
     /**
      * Parses an object from a response.
      * Parses an object from a response.
      *
      *
-     * @param uri The source of the response, after any redirection.
+     * @param uri The source {@link Uri} of the response, after any redirection.
      * @param inputStream An {@link InputStream} from which the response data can be read.
      * @param inputStream An {@link InputStream} from which the response data can be read.
      * @return The parsed object.
      * @return The parsed object.
      * @throws ParserException If an error occurs parsing the data.
      * @throws ParserException If an error occurs parsing the data.
@@ -87,10 +87,8 @@ public final class ParsingLoadable<T> implements Loadable {
   }
   }
 
 
   /**
   /**
-   * Returns the number of bytes loaded.
-   * <p>
-   * In the case that the network response was compressed, the value returned is the size of the
-   * data <em>after</em> decompression.
+   * Returns the number of bytes loaded. In the case that the network response was compressed, the
+   * value returned is the size of the data <em>after</em> decompression.
    *
    *
    * @return The number of bytes loaded.
    * @return The number of bytes loaded.
    */
    */

library/src/main/java/com/google/android/exoplayer2/upstream/TransferListener.java

@@ -16,12 +16,12 @@
 package com.google.android.exoplayer2.upstream;
 package com.google.android.exoplayer2.upstream;
 
 
 /**
 /**
- * Interface definition for a callback to be notified of data transfer events.
+ * A listener of data transfer events.
  */
  */
 public interface TransferListener {
 public interface TransferListener {
 
 
   /**
   /**
-   * Invoked when a transfer starts.
+   * Called when a transfer starts.
    */
    */
   void onTransferStart();
   void onTransferStart();
 
 
@@ -34,7 +34,7 @@ public interface TransferListener {
   void onBytesTransferred(int bytesTransferred);
   void onBytesTransferred(int bytesTransferred);
 
 
   /**
   /**
-   * Invoked when a transfer ends.
+   * Called when a transfer ends.
    */
    */
   void onTransferEnd();
   void onTransferEnd();
 
 

library/src/main/java/com/google/android/exoplayer2/upstream/cache/CacheDataSink.java

@@ -64,7 +64,7 @@ public final class CacheDataSink implements DataSink {
   }
   }
 
 
   @Override
   @Override
-  public DataSink open(DataSpec dataSpec) throws CacheDataSinkException {
+  public void open(DataSpec dataSpec) throws CacheDataSinkException {
     // TODO: Support caching for unbounded requests. See TODO in {@link CacheDataSource} for
     // TODO: Support caching for unbounded requests. See TODO in {@link CacheDataSource} for
     // more details.
     // more details.
     Assertions.checkState(dataSpec.length != C.LENGTH_UNBOUNDED);
     Assertions.checkState(dataSpec.length != C.LENGTH_UNBOUNDED);
@@ -72,7 +72,6 @@ public final class CacheDataSink implements DataSink {
       this.dataSpec = dataSpec;
       this.dataSpec = dataSpec;
       dataSpecBytesWritten = 0;
       dataSpecBytesWritten = 0;
       openNextOutputStream();
       openNextOutputStream();
-      return this;
     } catch (FileNotFoundException e) {
     } catch (FileNotFoundException e) {
       throw new CacheDataSinkException(e);
       throw new CacheDataSinkException(e);
     }
     }

library/src/main/java/com/google/android/exoplayer2/util/ColorParser.java

@@ -44,10 +44,22 @@ public final class ColorParser {
 
 
   private static final Map<String, Integer> COLOR_MAP;
   private static final Map<String, Integer> COLOR_MAP;
 
 
+  /**
+   * Parses a TTML color expression.
+   *
+   * @param colorExpression The color expression.
+   * @return The parsed ARGB color.
+   */
   public static int parseTtmlColor(String colorExpression) {
   public static int parseTtmlColor(String colorExpression) {
     return parseColorInternal(colorExpression, false);
     return parseColorInternal(colorExpression, false);
   }
   }
 
 
+  /**
+   * Parses a CSS color expression.
+   *
+   * @param colorExpression The color expression.
+   * @return The parsed ARGB color.
+   */
   public static int parseCssColor(String colorExpression) {
   public static int parseCssColor(String colorExpression) {
     return parseColorInternal(colorExpression, true);
     return parseColorInternal(colorExpression, true);
   }
   }

library/src/main/java/com/google/android/exoplayer2/util/LongArray.java

@@ -51,7 +51,7 @@ public final class LongArray {
   }
   }
 
 
   /**
   /**
-   * Gets a value.
+   * Returns the value at a specified index.
    *
    *
    * @param index The index.
    * @param index The index.
    * @return The corresponding value.
    * @return The corresponding value.
@@ -66,9 +66,7 @@ public final class LongArray {
   }
   }
 
 
   /**
   /**
-   * Gets the current size of the array.
-   *
-   * @return The current size of the array.
+   * Returns the current size of the array.
    */
    */
   public int size() {
   public int size() {
     return size;
     return size;

library/src/main/java/com/google/android/exoplayer2/util/MediaClock.java

@@ -21,7 +21,7 @@ package com.google.android.exoplayer2.util;
 public interface MediaClock {
 public interface MediaClock {
 
 
   /**
   /**
-   * @return The current media position in microseconds.
+   * Returns the current media position in microseconds.
    */
    */
   long getPositionUs();
   long getPositionUs();
 
 

library/src/main/java/com/google/android/exoplayer2/util/NalUnitUtil.java

@@ -209,7 +209,7 @@ public final class NalUnitUtil {
   }
   }
 
 
   /**
   /**
-   * Gets the type of the NAL unit in {@code data} that starts at {@code offset}.
+   * Returns the type of the NAL unit in {@code data} that starts at {@code offset}.
    *
    *
    * @param data The data to search.
    * @param data The data to search.
    * @param offset The start offset of a NAL unit. Must lie between {@code -3} (inclusive) and
    * @param offset The start offset of a NAL unit. Must lie between {@code -3} (inclusive) and
@@ -221,7 +221,7 @@ public final class NalUnitUtil {
   }
   }
 
 
   /**
   /**
-   * Gets the type of the H.265 NAL unit in {@code data} that starts at {@code offset}.
+   * Returns the type of the H.265 NAL unit in {@code data} that starts at {@code offset}.
    *
    *
    * @param data The data to search.
    * @param data The data to search.
    * @param offset The start offset of a NAL unit. Must lie between {@code -3} (inclusive) and
    * @param offset The start offset of a NAL unit. Must lie between {@code -3} (inclusive) and

library/src/main/java/com/google/android/exoplayer2/util/ParsableBitArray.java

@@ -28,7 +28,9 @@ public final class ParsableBitArray {
   private int bitOffset;
   private int bitOffset;
   private int byteLimit;
   private int byteLimit;
 
 
-  /** Creates a new instance that initially has no backing data. */
+  /**
+   * Creates a new instance that initially has no backing data.
+   */
   public ParsableBitArray() {}
   public ParsableBitArray() {}
 
 
   /**
   /**
@@ -81,9 +83,7 @@ public final class ParsableBitArray {
   }
   }
 
 
   /**
   /**
-   * Gets the current bit offset.
-   *
-   * @return The current bit offset.
+   * Returns the current bit offset.
    */
    */
   public int getPosition() {
   public int getPosition() {
     return byteOffset * 8 + bitOffset;
     return byteOffset * 8 + bitOffset;

library/src/main/java/com/google/android/exoplayer2/util/ParsableByteArray.java

@@ -29,16 +29,22 @@ public final class ParsableByteArray {
   private int position;
   private int position;
   private int limit;
   private int limit;
 
 
-  /** Creates a new instance that initially has no backing data. */
+  /**
+   * Creates a new instance that initially has no backing data.
+   */
   public ParsableByteArray() {}
   public ParsableByteArray() {}
 
 
-  /** Creates a new instance with {@code length} bytes. */
+  /**
+   * Creates a new instance with {@code length} bytes.
+   */
   public ParsableByteArray(int length) {
   public ParsableByteArray(int length) {
     this.data = new byte[length];
     this.data = new byte[length];
     limit = data.length;
     limit = data.length;
   }
   }
 
 
-  /** Creates a new instance wrapping {@code data}. */
+  /**
+   * Creates a new instance wrapping {@code data}.
+   */
   public ParsableByteArray(byte[] data) {
   public ParsableByteArray(byte[] data) {
     this.data = data;
     this.data = data;
     limit = data.length;
     limit = data.length;
@@ -75,12 +81,16 @@ public final class ParsableByteArray {
     limit = 0;
     limit = 0;
   }
   }
 
 
-  /** Returns the number of bytes yet to be read. */
+  /**
+   * Returns the number of bytes yet to be read.
+   */
   public int bytesLeft() {
   public int bytesLeft() {
     return limit - position;
     return limit - position;
   }
   }
 
 
-  /** Returns the limit. */
+  /**
+   * Returns the limit.
+   */
   public int limit() {
   public int limit() {
     return limit;
     return limit;
   }
   }
@@ -95,12 +105,16 @@ public final class ParsableByteArray {
     this.limit = limit;
     this.limit = limit;
   }
   }
 
 
-  /** Returns the current offset in the array, in bytes. */
+  /**
+   * Returns the current offset in the array, in bytes.
+   */
   public int getPosition() {
   public int getPosition() {
     return position;
     return position;
   }
   }
 
 
-  /** Returns the capacity of the array, which may be larger than the limit. */
+  /**
+   * Returns the capacity of the array, which may be larger than the limit.
+   */
   public int capacity() {
   public int capacity() {
     return data == null ? 0 : data.length;
     return data == null ? 0 : data.length;
   }
   }
@@ -160,55 +174,73 @@ public final class ParsableByteArray {
     position += length;
     position += length;
   }
   }
 
 
-  /** Reads the next byte as an unsigned value. */
+  /**
+   * Reads the next byte as an unsigned value.
+   */
   public int readUnsignedByte() {
   public int readUnsignedByte() {
     return (data[position++] & 0xFF);
     return (data[position++] & 0xFF);
   }
   }
 
 
-  /** Reads the next two bytes as an unsigned value. */
+  /**
+   * Reads the next two bytes as an unsigned value.
+   */
   public int readUnsignedShort() {
   public int readUnsignedShort() {
     return (data[position++] & 0xFF) << 8
     return (data[position++] & 0xFF) << 8
         | (data[position++] & 0xFF);
         | (data[position++] & 0xFF);
   }
   }
 
 
-  /** Reads the next two bytes as an unsigned value. */
+  /**
+   * Reads the next two bytes as an unsigned value.
+   */
   public int readLittleEndianUnsignedShort() {
   public int readLittleEndianUnsignedShort() {
     return (data[position++] & 0xFF) | (data[position++] & 0xFF) << 8;
     return (data[position++] & 0xFF) | (data[position++] & 0xFF) << 8;
   }
   }
 
 
-  /** Reads the next two bytes as an signed value. */
+  /**
+   * Reads the next two bytes as an signed value.
+   */
   public short readShort() {
   public short readShort() {
     return (short) ((data[position++] & 0xFF) << 8
     return (short) ((data[position++] & 0xFF) << 8
         | (data[position++] & 0xFF));
         | (data[position++] & 0xFF));
   }
   }
 
 
-  /** Reads the next two bytes as a signed value. */
+  /**
+   * Reads the next two bytes as a signed value.
+   */
   public short readLittleEndianShort() {
   public short readLittleEndianShort() {
     return (short) ((data[position++] & 0xFF) | (data[position++] & 0xFF) << 8);
     return (short) ((data[position++] & 0xFF) | (data[position++] & 0xFF) << 8);
   }
   }
 
 
-  /** Reads the next three bytes as an unsigned value. */
+  /**
+   * Reads the next three bytes as an unsigned value.
+   */
   public int readUnsignedInt24() {
   public int readUnsignedInt24() {
     return (data[position++] & 0xFF) << 16
     return (data[position++] & 0xFF) << 16
         | (data[position++] & 0xFF) << 8
         | (data[position++] & 0xFF) << 8
         | (data[position++] & 0xFF);
         | (data[position++] & 0xFF);
   }
   }
 
 
-  /** Reads the next three bytes as a signed value in little endian order. */
+  /**
+   * Reads the next three bytes as a signed value in little endian order.
+   */
   public int readLittleEndianInt24() {
   public int readLittleEndianInt24() {
     return (data[position++] & 0xFF)
     return (data[position++] & 0xFF)
         | (data[position++] & 0xFF) << 8
         | (data[position++] & 0xFF) << 8
         | (data[position++] & 0xFF) << 16;
         | (data[position++] & 0xFF) << 16;
   }
   }
 
 
-  /**  Reads the next three bytes as an unsigned value in little endian order. */
+  /**
+   * Reads the next three bytes as an unsigned value in little endian order.
+   */
   public int readLittleEndianUnsignedInt24() {
   public int readLittleEndianUnsignedInt24() {
     return (data[position++] & 0xFF)
     return (data[position++] & 0xFF)
         | (data[position++] & 0xFF) << 8
         | (data[position++] & 0xFF) << 8
         | (data[position++] & 0xFF) << 16;
         | (data[position++] & 0xFF) << 16;
   }
   }
 
 
-  /** Reads the next four bytes as an unsigned value. */
+  /**
+   * Reads the next four bytes as an unsigned value.
+   */
   public long readUnsignedInt() {
   public long readUnsignedInt() {
     return (data[position++] & 0xFFL) << 24
     return (data[position++] & 0xFFL) << 24
         | (data[position++] & 0xFFL) << 16
         | (data[position++] & 0xFFL) << 16
@@ -216,7 +248,9 @@ public final class ParsableByteArray {
         | (data[position++] & 0xFFL);
         | (data[position++] & 0xFFL);
   }
   }
 
 
-  /** Reads the next four bytes as an unsigned value in little endian order. */
+  /**
+   * Reads the next four bytes as an unsigned value in little endian order.
+   */
   public long readLittleEndianUnsignedInt() {
   public long readLittleEndianUnsignedInt() {
     return (data[position++] & 0xFFL)
     return (data[position++] & 0xFFL)
         | (data[position++] & 0xFFL) << 8
         | (data[position++] & 0xFFL) << 8
@@ -224,7 +258,9 @@ public final class ParsableByteArray {
         | (data[position++] & 0xFFL) << 24;
         | (data[position++] & 0xFFL) << 24;
   }
   }
 
 
-  /** Reads the next four bytes as a signed value. */
+  /**
+   * Reads the next four bytes as a signed value
+   */
   public int readInt() {
   public int readInt() {
     return (data[position++] & 0xFF) << 24
     return (data[position++] & 0xFF) << 24
         | (data[position++] & 0xFF) << 16
         | (data[position++] & 0xFF) << 16
@@ -232,7 +268,9 @@ public final class ParsableByteArray {
         | (data[position++] & 0xFF);
         | (data[position++] & 0xFF);
   }
   }
 
 
-  /** Reads the next four bytes as an signed value in little endian order. */
+  /**
+   * Reads the next four bytes as an signed value in little endian order.
+   */
   public int readLittleEndianInt() {
   public int readLittleEndianInt() {
     return (data[position++] & 0xFF)
     return (data[position++] & 0xFF)
         | (data[position++]  & 0xFF) << 8
         | (data[position++]  & 0xFF) << 8
@@ -240,7 +278,9 @@ public final class ParsableByteArray {
         | (data[position++]  & 0xFF) << 24;
         | (data[position++]  & 0xFF) << 24;
   }
   }
 
 
-  /** Reads the next eight bytes as a signed value. */
+  /**
+   * Reads the next eight bytes as a signed value.
+   */
   public long readLong() {
   public long readLong() {
     return (data[position++] & 0xFFL) << 56
     return (data[position++] & 0xFFL) << 56
         | (data[position++] & 0xFFL) << 48
         | (data[position++] & 0xFFL) << 48
@@ -252,7 +292,9 @@ public final class ParsableByteArray {
         | (data[position++] & 0xFFL);
         | (data[position++] & 0xFFL);
   }
   }
 
 
-  /** Reads the next eight bytes as a signed value in little endian order. */
+  /**
+   * Reads the next eight bytes as a signed value in little endian order.
+   */
   public long readLittleEndianLong() {
   public long readLittleEndianLong() {
     return (data[position++] & 0xFFL)
     return (data[position++] & 0xFFL)
         | (data[position++] & 0xFFL) << 8
         | (data[position++] & 0xFFL) << 8
@@ -264,7 +306,9 @@ public final class ParsableByteArray {
         | (data[position++] & 0xFFL) << 56;
         | (data[position++] & 0xFFL) << 56;
   }
   }
 
 
-  /** Reads the next four bytes, returning the integer portion of the fixed point 16.16 integer. */
+  /**
+   * Reads the next four bytes, returning the integer portion of the fixed point 16.16 integer.
+   */
   public int readUnsignedFixedPoint1616() {
   public int readUnsignedFixedPoint1616() {
     int result = (data[position++] & 0xFF) << 8
     int result = (data[position++] & 0xFF) << 8
         | (data[position++] & 0xFF);
         | (data[position++] & 0xFF);
@@ -328,7 +372,9 @@ public final class ParsableByteArray {
     return result;
     return result;
   }
   }
 
 
-  /** Reads the next eight bytes as a 64-bit floating point value. */
+  /**
+   * Reads the next eight bytes as a 64-bit floating point value.
+   */
   public double readDouble() {
   public double readDouble() {
     return Double.longBitsToDouble(readLong());
     return Double.longBitsToDouble(readLong());
   }
   }
@@ -398,6 +444,7 @@ public final class ParsableByteArray {
 
 
   /**
   /**
    * Reads a long value encoded by UTF-8 encoding
    * Reads a long value encoded by UTF-8 encoding
+   *
    * @throws NumberFormatException if there is a problem with decoding
    * @throws NumberFormatException if there is a problem with decoding
    * @return Decoded long value
    * @return Decoded long value
    */
    */

library/src/main/java/com/google/android/exoplayer2/util/PriorityTaskManager.java

@@ -52,9 +52,7 @@ public final class PriorityTaskManager {
   }
   }
 
 
   /**
   /**
-   * Register a new task.
-   * <p>
-   * The task must call {@link #remove(int)} when done.
+   * Register a new task. The task must call {@link #remove(int)} when done.
    *
    *
    * @param priority The priority of the task.
    * @param priority The priority of the task.
    */
    */

library/src/main/java/com/google/android/exoplayer2/util/SlidingPercentile.java

@@ -20,13 +20,14 @@ import java.util.Collections;
 import java.util.Comparator;
 import java.util.Comparator;
 
 
 /**
 /**
- * Calculate any percentile over a sliding window of weighted values. A maximum total weight is
- * configured. Once the maximum weight is reached, the oldest value is reduced in weight until it
- * reaches zero and is removed. This maintains a constant total weight at steady state.
+ * Calculate any percentile over a sliding window of weighted values. A maximum weight is
+ * configured. Once the total weight of the values reaches the maximum weight, the oldest value is
+ * reduced in weight until it reaches zero and is removed. This maintains a constant total weight,
+ * equal to the maximum allowed, at the steady state.
  * <p>
  * <p>
- * SlidingPercentile can be used for bandwidth estimation based on a sliding window of past
- * download rate observations. This is an alternative to sliding mean and exponential averaging
- * which suffer from susceptibility to outliers and slow adaptation to step functions.
+ * This class can be used for bandwidth estimation based on a sliding window of past transfer rate
+ * observations. This is an alternative to sliding mean and exponential averaging which suffer from
+ * susceptibility to outliers and slow adaptation to step functions.
  *
  *
  * @see <a href="http://en.wikipedia.org/wiki/Moving_average">Wiki: Moving average</a>
  * @see <a href="http://en.wikipedia.org/wiki/Moving_average">Wiki: Moving average</a>
  * @see <a href="http://en.wikipedia.org/wiki/Selection_algorithm">Wiki: Selection algorithm</a>
  * @see <a href="http://en.wikipedia.org/wiki/Selection_algorithm">Wiki: Selection algorithm</a>
@@ -64,6 +65,9 @@ public final class SlidingPercentile {
   private int totalWeight;
   private int totalWeight;
   private int recycledSampleCount;
   private int recycledSampleCount;
 
 
+  /**
+   * @param maxWeight The maximum weight.
+   */
   public SlidingPercentile(int maxWeight) {
   public SlidingPercentile(int maxWeight) {
     this.maxWeight = maxWeight;
     this.maxWeight = maxWeight;
     recycledSamples = new Sample[MAX_RECYCLED_SAMPLES];
     recycledSamples = new Sample[MAX_RECYCLED_SAMPLES];
@@ -72,8 +76,7 @@ public final class SlidingPercentile {
   }
   }
 
 
   /**
   /**
-   * Record a new observation. Respect the configured total weight by reducing in weight or
-   * removing the oldest observations as required.
+   * Adds a new weighted value.
    *
    *
    * @param weight The weight of the new observation.
    * @param weight The weight of the new observation.
    * @param value The value of the new observation.
    * @param value The value of the new observation.
@@ -106,10 +109,10 @@ public final class SlidingPercentile {
   }
   }
 
 
   /**
   /**
-   * Compute the percentile by integration.
+   * Computes a percentile by integration.
    *
    *
    * @param percentile The desired percentile, expressed as a fraction in the range (0,1].
    * @param percentile The desired percentile, expressed as a fraction in the range (0,1].
-   * @return The requested percentile value or Float.NaN.
+   * @return The requested percentile value or {@link Float#NaN} if no samples have been added.
    */
    */
   public float getPercentile(float percentile) {
   public float getPercentile(float percentile) {
     ensureSortedByValue();
     ensureSortedByValue();
@@ -127,7 +130,7 @@ public final class SlidingPercentile {
   }
   }
 
 
   /**
   /**
-   * Sort the samples by index, if not already.
+   * Sorts the samples by index.
    */
    */
   private void ensureSortedByIndex() {
   private void ensureSortedByIndex() {
     if (currentSortOrder != SORT_ORDER_BY_INDEX) {
     if (currentSortOrder != SORT_ORDER_BY_INDEX) {
@@ -137,7 +140,7 @@ public final class SlidingPercentile {
   }
   }
 
 
   /**
   /**
-   * Sort the samples by value, if not already.
+   * Sorts the samples by value.
    */
    */
   private void ensureSortedByValue() {
   private void ensureSortedByValue() {
     if (currentSortOrder != SORT_ORDER_BY_VALUE) {
     if (currentSortOrder != SORT_ORDER_BY_VALUE) {

library/src/main/java/com/google/android/exoplayer2/util/XmlPullParserUtil.java

@@ -25,23 +25,61 @@ public final class XmlPullParserUtil {
 
 
   private XmlPullParserUtil() {}
   private XmlPullParserUtil() {}
 
 
+  /**
+   * Returns whether the current event is an end tag with the specified name.
+   *
+   * @param xpp The {@link XmlPullParser} to query.
+   * @param name The specified name.
+   * @return True if the current event is an end tag with the specified name. False otherwise.
+   * @throws XmlPullParserException If an error occurs querying the parser.
+   */
   public static boolean isEndTag(XmlPullParser xpp, String name) throws XmlPullParserException {
   public static boolean isEndTag(XmlPullParser xpp, String name) throws XmlPullParserException {
     return isEndTag(xpp) && xpp.getName().equals(name);
     return isEndTag(xpp) && xpp.getName().equals(name);
   }
   }
 
 
+  /**
+   * Returns whether the current event is an end tag.
+   *
+   * @param xpp The {@link XmlPullParser} to query.
+   * @return True if the current event is an end tag. False otherwise.
+   * @throws XmlPullParserException If an error occurs querying the parser.
+   */
   public static boolean isEndTag(XmlPullParser xpp) throws XmlPullParserException {
   public static boolean isEndTag(XmlPullParser xpp) throws XmlPullParserException {
     return xpp.getEventType() == XmlPullParser.END_TAG;
     return xpp.getEventType() == XmlPullParser.END_TAG;
   }
   }
 
 
+  /**
+   * Returns whether the current event is a start tag with the specified name.
+   *
+   * @param xpp The {@link XmlPullParser} to query.
+   * @param name The specified name.
+   * @return True if the current event is a start tag with the specified name. False otherwise.
+   * @throws XmlPullParserException If an error occurs querying the parser.
+   */
   public static boolean isStartTag(XmlPullParser xpp, String name)
   public static boolean isStartTag(XmlPullParser xpp, String name)
       throws XmlPullParserException {
       throws XmlPullParserException {
     return isStartTag(xpp) && xpp.getName().equals(name);
     return isStartTag(xpp) && xpp.getName().equals(name);
   }
   }
 
 
+  /**
+   * Returns whether the current event is a start tag.
+   *
+   * @param xpp The {@link XmlPullParser} to query.
+   * @return True if the current event is a start tag. False otherwise.
+   * @throws XmlPullParserException If an error occurs querying the parser.
+   */
   public static boolean isStartTag(XmlPullParser xpp) throws XmlPullParserException {
   public static boolean isStartTag(XmlPullParser xpp) throws XmlPullParserException {
     return xpp.getEventType() == XmlPullParser.START_TAG;
     return xpp.getEventType() == XmlPullParser.START_TAG;
   }
   }
 
 
+  /**
+   * Returns the value of an attribute of the current start tag.
+   *
+   * @param xpp The {@link XmlPullParser} to query.
+   * @param attributeName The name of the attribute.
+   * @return The value of the attribute, or null if the current event is not a start tag or if no
+   *     no such attribute was found.
+   */
   public static String getAttributeValue(XmlPullParser xpp, String attributeName) {
   public static String getAttributeValue(XmlPullParser xpp, String attributeName) {
     int attributeCount = xpp.getAttributeCount();
     int attributeCount = xpp.getAttributeCount();
     for (int i = 0; i < attributeCount; i++) {
     for (int i = 0; i < attributeCount; i++) {