Improve CacheKeyFactory documentation

- To make it clear that cache keys are for whole resources
- To explicitly make it clear to implementors that deriving a cache key
  from position and length is invalid. We've seen at least one developer
  trying to do this [1], so it seems worthwhile to be explicit!

[1] https://github.com/google/ExoPlayer/issues/5978#issuecomment-618977036

Issue: #5978
PiperOrigin-RevId: 312643930

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

@@ -25,10 +25,15 @@ public interface CacheKeyFactory {
       (dataSpec) -> dataSpec.key != null ? dataSpec.key : dataSpec.uri.toString();
       (dataSpec) -> dataSpec.key != null ? dataSpec.key : dataSpec.uri.toString();
 
 
   /**
   /**
-   * Returns a cache key for the given {@link DataSpec}.
+   * Returns the cache key of the resource containing the data defined by a {@link DataSpec}.
    *
    *
-   * @param dataSpec The data being cached.
-   * @return The cache key.
+   * <p>Note that since the returned cache key corresponds to the whole resource, implementations
+   * must not return different cache keys for {@link DataSpec DataSpecs} that define different
+   * ranges of the same resource. As a result, implementations should not use fields such as {@link
+   * DataSpec#position} and {@link DataSpec#length}.
+   *
+   * @param dataSpec The {@link DataSpec}.
+   * @return The cache key of the resource.
    */
    */
   String buildCacheKey(DataSpec dataSpec);
   String buildCacheKey(DataSpec dataSpec);
 }
 }