diff --git a/library/core/src/main/java/com/google/android/exoplayer2/upstream/DataSpec.java b/library/core/src/main/java/com/google/android/exoplayer2/upstream/DataSpec.java
index cbe971bc5d..a6b89a334d 100644
--- a/library/core/src/main/java/com/google/android/exoplayer2/upstream/DataSpec.java
+++ b/library/core/src/main/java/com/google/android/exoplayer2/upstream/DataSpec.java
@@ -49,7 +49,8 @@ public final class DataSpec {
   public static final int FLAG_ALLOW_GZIP = 1 << 0;
 
   /**
-   * Permits content to be cached even if its length can not be resolved.
+   * Permits content to be cached even if its length can not be resolved. Typically this's the case
+   * for progressive live streams and when {@link #FLAG_ALLOW_GZIP} is used.
    */
   public static final int FLAG_ALLOW_CACHING_UNKNOWN_LENGTH = 1 << 1;
 
diff --git a/library/core/src/main/java/com/google/android/exoplayer2/upstream/cache/CacheDataSink.java b/library/core/src/main/java/com/google/android/exoplayer2/upstream/cache/CacheDataSink.java
index 33b1ca58b0..1af690e10f 100644
--- a/library/core/src/main/java/com/google/android/exoplayer2/upstream/cache/CacheDataSink.java
+++ b/library/core/src/main/java/com/google/android/exoplayer2/upstream/cache/CacheDataSink.java
@@ -29,6 +29,11 @@ import java.io.OutputStream;
 
 /**
  * Writes data into a cache.
+ *
+ * <p>If the {@link DataSpec} object used with {@link #open(DataSpec)} method call has the {@code
+ * length} field set to {@link C#LENGTH_UNSET} but {@link
+ * DataSpec#FLAG_ALLOW_CACHING_UNKNOWN_LENGTH} isn't set then {@link #write(byte[], int, int)} calls
+ * are ignored.
  */
 public final class CacheDataSink implements DataSink {
 
diff --git a/library/core/src/main/java/com/google/android/exoplayer2/upstream/cache/CacheDataSource.java b/library/core/src/main/java/com/google/android/exoplayer2/upstream/cache/CacheDataSource.java
index 2b151943a5..f1d50a43e4 100644
--- a/library/core/src/main/java/com/google/android/exoplayer2/upstream/cache/CacheDataSource.java
+++ b/library/core/src/main/java/com/google/android/exoplayer2/upstream/cache/CacheDataSource.java
@@ -35,6 +35,10 @@ import java.lang.annotation.RetentionPolicy;
  * A {@link DataSource} that reads and writes a {@link Cache}. Requests are fulfilled from the cache
  * when possible. When data is not cached it is requested from an upstream {@link DataSource} and
  * written into the cache.
+ *
+ * <p>By default requests whose length can not be resolved are not cached. This is to prevent
+ * caching of progressive live streams, which should usually not be cached. Caching of this kind of
+ * requests can be enabled per request with {@link DataSpec#FLAG_ALLOW_CACHING_UNKNOWN_LENGTH}.
  */
 public final class CacheDataSource implements DataSource {
 
@@ -67,7 +71,8 @@ public final class CacheDataSource implements DataSource {
   public static final int FLAG_IGNORE_CACHE_ON_ERROR = 1 << 1;
 
   /**
-   * A flag indicating that the cache should be bypassed for requests whose lengths are unset.
+   * A flag indicating that the cache should be bypassed for requests whose lengths are unset. This
+   * flag is provided for legacy reasons only.
    */
   public static final int FLAG_IGNORE_CACHE_FOR_UNSET_LENGTH_REQUESTS = 1 << 2;