Document DataSource edge-case behaviors

PiperOrigin-RevId: 362386100

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

@@ -45,17 +45,31 @@ public interface DataSource extends DataReader {
   void addTransferListener(TransferListener transferListener);
 
   /**
-   * Opens the source to read the specified data.
-   * <p>
-   * 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.
+   * Opens the source to read the specified data. If an {@link IOException} is thrown, callers must
+   * still call {@link #close()} to ensure that any partial effects of the invocation are cleaned
+   * up.
+   *
+   * <p>The following edge case behaviors apply:
+   *
+   * <ul>
+   *   <li>If the {@link DataSpec#position requested position} is within the resource, but the
+   *       {@link DataSpec#length requested length} extends beyond the end of the resource, then
+   *       {@link #open} will succeed and data from the requested position to the end of the
+   *       resource will be made available through {@link #read}.
+   *   <li>If the {@link DataSpec#position requested position} is equal to the length of the
+   *       resource, then {@link #open} will succeed, and {@link #read} will immediately return
+   *       {@link C#RESULT_END_OF_INPUT}.
+   *   <li>If the {@link DataSpec#position requested position} is greater than the length of the
+   *       resource, then {@link #open} will throw an {@link IOException} for which {@link
+   *       DataSourceException#isCausedByPositionOutOfRange} will be {@code true}.
+   * </ul>
    *
    * @param dataSpec Defines the data to be read.
    * @throws IOException If an error occurs opening the source. {@link DataSourceException} can be
    *     thrown or used as a cause of the thrown exception to specify the reason of the error.
    * @return The number of bytes that can be read from the opened source. For unbounded requests
-   *     (i.e. requests where {@link DataSpec#length} equals {@link C#LENGTH_UNSET}) this value
-   *     is the resolved length of the request, or {@link C#LENGTH_UNSET} if the length is still
+   *     (i.e., requests where {@link DataSpec#length} equals {@link C#LENGTH_UNSET}) this value is
+   *     the resolved length of the request, or {@link C#LENGTH_UNSET} if the length is still
    *     unresolved. For all other requests, the value returned will be equal to the request's
    *     {@link DataSpec#length}.
    */
@@ -82,10 +96,8 @@ public interface DataSource extends DataReader {
   }
 
   /**
-   * Closes the source.
-   * <p>
-   * 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.
+   * Closes the source. This method must be called even if the corresponding call to {@link
+   * #open(DataSpec)} threw an {@link IOException}.
    *
    * @throws IOException If an error occurs closing the source.
    */