Summary

Modify the descriptions of the return value for some bulk read (read(byte[],int,int)) methods in java.io to be consistent and more accurate.

Problem

The descriptions of the return value for some bulk read (read(byte[],int,int)) methods in java.io are inconsistent and ambiguous.

Solution

Change the problematic verbiage to:

the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.

Specification

--- a/src/java.base/share/classes/java/io/ObjectInput.java
+++ b/src/java.base/share/classes/java/io/ObjectInput.java
@@ -62,8 +62,9 @@ public interface ObjectInput extends DataInput, AutoCloseable {
      * Reads into an array of bytes.  This method will
      * block until some input is available.
      * @param   b the buffer into which the data is read
-     * @return  the actual number of bytes read, -1 is
-     *          returned when the end of the stream is reached.
+     * @return  the total number of bytes read into the buffer, or
+     *          {@code -1} if there is no more data because the end of
+     *          the stream has been reached.
      * @throws  IOException If an I/O error has occurred.
      */
     public int read(byte[] b) throws IOException;
@@ -74,8 +75,9 @@ public interface ObjectInput extends DataInput, AutoCloseable {
      * @param   b the buffer into which the data is read
      * @param   off the start offset of the data
      * @param   len the maximum number of bytes read
-     * @return  the actual number of bytes read, -1 is
-     *          returned when the end of the stream is reached.
+     * @return  the total number of bytes read into the buffer, or
+     *          {@code -1} if there is no more data because the end of
+     *          the stream has been reached.
      * @throws  IOException If an I/O error has occurred.
      */
     public int read(byte[] b, int off, int len) throws IOException;
diff --git a/src/java.base/share/classes/java/io/ObjectInputStream.java b/src/java.base/share/classes/java/io/ObjectInputStream.java
index 14812fea9ad..319981e864b 100644
--- a/src/java.base/share/classes/java/io/ObjectInputStream.java
+++ b/src/java.base/share/classes/java/io/ObjectInputStream.java
@@ -1031,8 +1031,9 @@ public class ObjectInputStream
      * @param   buf the buffer into which the data is read
      * @param   off the start offset in the destination array {@code buf}
      * @param   len the maximum number of bytes read
-     * @return  the actual number of bytes read, -1 is returned when the end of
-     *          the stream is reached.
+     * @return  the total number of bytes read into the buffer, or
+     *          {@code -1} if there is no more data because the end of
+     *          the stream has been reached.
      * @throws  NullPointerException if {@code buf} is {@code null}.
      * @throws  IndexOutOfBoundsException if {@code off} is negative,
      *          {@code len} is negative, or {@code len} is greater than
diff --git a/src/java.base/share/classes/java/io/SequenceInputStream.java b/src/java.base/share/classes/java/io/SequenceInputStream.java
index 5f692ce6c44..95d489e7d54 100644
--- a/src/java.base/share/classes/java/io/SequenceInputStream.java
+++ b/src/java.base/share/classes/java/io/SequenceInputStream.java
@@ -177,7 +177,9 @@ public class SequenceInputStream extends InputStream {
      * @param      off   the start offset in array {@code b}
      *                   at which the data is written.
      * @param      len   the maximum number of bytes read.
-     * @return     int   the number of bytes read.
+     * @return     the total number of bytes read into the buffer, or
+     *             {@code -1} if there is no more data because the end of
+     *             the last contained stream has been reached.
      * @throws     NullPointerException If {@code b} is {@code null}.
      * @throws     IndexOutOfBoundsException If {@code off} is negative,
      *             {@code len} is negative, or {@code len} is