Froyo InputStream.available documentation improvement.

This method causes a lot of confusion, and we can do a lot better. (Ideally,
the API would either not exist or be something like "public boolean ready()".)

I've removed poor-quality documentation overrides too, so the full
documentation is visible in most places. (InflaterInputStream is an obvious
exception.)

Also, to a lesser extent, improve the InputStream.skip documentation.

Change-Id: I6d6cd788e6a32ad4a2613d1e381610f1ad8575fe

11 files changed, 59 insertions, 88 deletions

diff --git a/luni/src/main/java/java/io/BufferedInputStream.java b/luni/src/main/java/java/io/BufferedInputStream.java
index 22379dd..6888a87 100644
--- a/luni/src/main/java/java/io/BufferedInputStream.java
+++ b/luni/src/main/java/java/io/BufferedInputStream.java
@@ -115,13 +115,13 @@ public class BufferedInputStream extends FilterInputStream {
     }
 
     /**
-     * Returns the number of bytes that are available before this stream will
-     * block. This method returns the number of bytes available in the buffer
-     * plus those available in the source stream.
+     * Returns an estimated number of bytes that can be read or skipped without blocking for more
+     * input. This method returns the number of bytes available in the buffer
+     * plus those available in the source stream, but see {@link InputStream#available} for
+     * important caveats.
      *
-     * @return the number of bytes available before blocking.
-     * @throws IOException
-     *             if this stream is closed.
+     * @return the estimated number of bytes available
+     * @throws IOException if this stream is closed or an error occurs
      */
     @Override
     public synchronized int available() throws IOException {
diff --git a/luni/src/main/java/java/io/ByteArrayInputStream.java b/luni/src/main/java/java/io/ByteArrayInputStream.java
index f0b7219..9b4b32f 100644
--- a/luni/src/main/java/java/io/ByteArrayInputStream.java
+++ b/luni/src/main/java/java/io/ByteArrayInputStream.java
@@ -85,11 +85,9 @@ public class ByteArrayInputStream extends InputStream {
     }
 
     /**
-     * Returns the number of bytes that are available before this stream will
-     * block. This method returns the number of bytes yet to be read from the
-     * source byte array.
+     * Returns the number of remaining bytes.
      *
-     * @return the number of bytes available before blocking.
+     * @return {@code count - pos}
      */
     @Override
     public synchronized int available() {
diff --git a/luni/src/main/java/java/io/FileInputStream.java b/luni/src/main/java/java/io/FileInputStream.java
index 20f7eae..6b91544 100644
--- a/luni/src/main/java/java/io/FileInputStream.java
+++ b/luni/src/main/java/java/io/FileInputStream.java
@@ -134,15 +134,6 @@ public class FileInputStream extends InputStream implements Closeable {
         this(null == fileName ? (File) null : new File(fileName));
     }
 
-    /**
-     * Returns the number of bytes that are available before this stream will
-     * block. This method always returns the size of the file minus the current
-     * position.
-     *
-     * @return the number of bytes available before blocking.
-     * @throws IOException
-     *             if an error occurs in this stream.
-     */
     @Override
     public int available() throws IOException {
         openCheck();
diff --git a/luni/src/main/java/java/io/FilterInputStream.java b/luni/src/main/java/java/io/FilterInputStream.java
index 0baa409..9891cdb 100644
--- a/luni/src/main/java/java/io/FilterInputStream.java
+++ b/luni/src/main/java/java/io/FilterInputStream.java
@@ -46,14 +46,6 @@ public class FilterInputStream extends InputStream {
         this.in = in;
     }
 
-    /**
-     * Returns the number of bytes that are available before this stream will
-     * block.
-     *
-     * @return the number of bytes available before blocking.
-     * @throws IOException
-     *             if an error occurs in this stream.
-     */
     @Override
     public int available() throws IOException {
         return in.available();
diff --git a/luni/src/main/java/java/io/InputStream.java b/luni/src/main/java/java/io/InputStream.java
index 33a5cfd..b16c5a2 100644
--- a/luni/src/main/java/java/io/InputStream.java
+++ b/luni/src/main/java/java/io/InputStream.java
@@ -48,13 +48,41 @@ public abstract class InputStream extends Object implements Closeable {
     }
 
     /**
-     * Returns the number of bytes that are available before this stream will
-     * block. This implementation always returns 0. Subclasses should override
-     * and indicate the correct number of bytes available.
+     * Returns an estimated number of bytes that can be read or skipped without blocking for more
+     * input.
      *
-     * @return the number of bytes available before blocking.
-     * @throws IOException
-     *             if an error occurs in this stream.
+     * <p>Note that this method provides such a weak guarantee that it is not very useful in
+     * practice.
+     *
+     * <p>Firstly, the guarantee is "without blocking for more input" rather than "without
+     * blocking": a read may still block waiting for I/O to complete&nbsp;&mdash; the guarantee is
+     * merely that it won't have to wait indefinitely for data to be written. The result of this
+     * method should not be used as a license to do I/O on a thread that shouldn't be blocked.
+     *
+     * <p>Secondly, the result is a
+     * conservative estimate and may be significantly smaller than the actual number of bytes
+     * available. In particular, an implementation that always returns 0 would be correct.
+     * In general, callers should only use this method if they'd be satisfied with
+     * treating the result as a boolean yes or no answer to the question "is there definitely
+     * data ready?".
+     *
+     * <p>Thirdly, the fact that a given number of bytes is "available" does not guarantee that a
+     * read or skip will actually read or skip that many bytes: they may read or skip fewer.
+     *
+     * <p>It is particularly important to realize that you <i>must not</i> use this method to
+     * size a container and assume that you can read the entirety of the stream without needing
+     * to resize the container. Such callers should probably write everything they read to a
+     * {@link ByteArrayOutputStream} and convert that to a byte array. Alternatively, if you're
+     * reading from a file, {@link File#length} returns the current length of the file (though
+     * assuming the file's length can't change may be incorrect, reading a file is inherently
+     * racy).
+     *
+     * <p>The default implementation of this method in {@code InputStream} always returns 0.
+     * Subclasses should override this method if they are able to indicate the number of bytes
+     * available.
+     *
+     * @return the estimated number of bytes available
+     * @throws IOException if this stream is closed or an error occurs
      */
     public int available() throws IOException {
         return 0;
@@ -198,15 +226,16 @@ public abstract class InputStream extends Object implements Closeable {
     }
 
     /**
-     * Skips at most {@code n} bytes in this stream. It does nothing and returns
-     * 0 if {@code n} is negative. Less than {@code n} characters are skipped if
-     * the end of this stream is reached before the operation completes.
-     * <p>
-     * This default implementation reads {@code n} bytes into a temporary
+     * Skips at most {@code n} bytes in this stream. This method does nothing and returns
+     * 0 if {@code n} is negative.
+     *
+     * <p>Note the "at most" in the description of this method: this method may choose to skip
+     * fewer bytes than requested. Callers should <i>always</i> check the return value.
+     *
+     * <p>This default implementation reads bytes into a temporary
      * buffer. Concrete subclasses should provide their own implementation.
      *
-     * @param n
-     *            the number of bytes to skip.
+     * @param n the number of bytes to skip.
      * @return the number of bytes actually skipped.
      * @throws IOException
      *             if this stream is closed or another IOException occurs.
diff --git a/luni/src/main/java/java/io/LineNumberInputStream.java b/luni/src/main/java/java/io/LineNumberInputStream.java
index 3df3a05..b8290cf 100644
--- a/luni/src/main/java/java/io/LineNumberInputStream.java
+++ b/luni/src/main/java/java/io/LineNumberInputStream.java
@@ -51,17 +51,12 @@ public class LineNumberInputStream extends FilterInputStream {
     }
 
     /**
-     * Returns the number of bytes that are available before this stream will
-     * block.
-     * <p>
-     * Note: The source stream may just be a sequence of {@code "\r\n"} bytes
+     * {@inheritDoc}
+     *
+     * <p>Note that the source stream may just be a sequence of {@code "\r\n"} bytes
      * which are converted into {@code '\n'} by this stream. Therefore,
      * {@code available} returns only {@code in.available() / 2} bytes as
      * result.
-     *
-     * @return the guaranteed number of bytes available before blocking.
-     * @throws IOException
-     *             if an error occurs in this stream.
      */
     @Override
     public int available() throws IOException {
diff --git a/luni/src/main/java/java/io/ObjectInputStream.java b/luni/src/main/java/java/io/ObjectInputStream.java
index df6d9a2..9d79641a 100644
--- a/luni/src/main/java/java/io/ObjectInputStream.java
+++ b/luni/src/main/java/java/io/ObjectInputStream.java
@@ -446,16 +446,6 @@ public class ObjectInputStream extends InputStream implements ObjectInput,
         primitiveData = emptyStream;
     }
 
-    /**
-     * Returns the number of bytes of primitive data that can be read from this
-     * stream without blocking. This method should not be used at any arbitrary
-     * position; just when reading primitive data types (int, char etc).
-     *
-     * @return the number of available primitive data bytes.
-     * @throws IOException
-     *             if any I/O problem occurs while computing the available
-     *             bytes.
-     */
     @Override
     public int available() throws IOException {
         // returns 0 if next data is an object, or N if reading primitive types
diff --git a/luni/src/main/java/java/io/PipedInputStream.java b/luni/src/main/java/java/io/PipedInputStream.java
index 6d1c007..025d6b1 100644
--- a/luni/src/main/java/java/io/PipedInputStream.java
+++ b/luni/src/main/java/java/io/PipedInputStream.java
@@ -103,13 +103,13 @@ public class PipedInputStream extends InputStream {
     }
 
     /**
-     * Returns the number of bytes that are available before this stream will
-     * block. This implementation returns the number of bytes written to this
-     * pipe that have not been read yet.
+     * {@inheritDoc}
      *
-     * @return the number of bytes available before blocking.
-     * @throws IOException
-     *             if an error occurs in this stream.
+     * <p>Unlike most streams, {@code PipedInputStream} returns 0 rather than throwing
+     * {@code IOException} if the stream has been closed. Unconnected and broken pipes also
+     * return 0.
+     *
+     * @throws IOException if an I/O error occurs
      */
     @Override
     public synchronized int available() throws IOException {
diff --git a/luni/src/main/java/java/io/PushbackInputStream.java b/luni/src/main/java/java/io/PushbackInputStream.java
index 932a896..5a78eb9 100644
--- a/luni/src/main/java/java/io/PushbackInputStream.java
+++ b/luni/src/main/java/java/io/PushbackInputStream.java
@@ -73,16 +73,6 @@ public class PushbackInputStream extends FilterInputStream {
         pos = size;
     }
 
-    /**
-     * Returns the number of bytes that are available before this stream will
-     * block. This is the sum of the bytes available in the pushback buffer and
-     * those available from the source stream.
-     *
-     * @return the number of bytes available before blocking.
-     * @throws IOException
-     *             if this stream is closed or an I/O error occurs in the source
-     *             stream.
-     */
     @Override
     public int available() throws IOException {
         if (buf == null) {
diff --git a/luni/src/main/java/java/io/SequenceInputStream.java b/luni/src/main/java/java/io/SequenceInputStream.java
index 3719021..c72e521 100644
--- a/luni/src/main/java/java/io/SequenceInputStream.java
+++ b/luni/src/main/java/java/io/SequenceInputStream.java
@@ -81,14 +81,6 @@ public class SequenceInputStream extends InputStream {
         }
     }
 
-    /**
-     * Returns the number of bytes that are available before the current input stream will
-     * block.
-     *
-     * @return the number of bytes available in the current input stream before blocking.
-     * @throws IOException
-     *             if an I/O error occurs in the current input stream.
-     */
     @Override
     public int available() throws IOException {
         if (e != null && in != null) {
diff --git a/luni/src/main/java/java/io/StringBufferInputStream.java b/luni/src/main/java/java/io/StringBufferInputStream.java
index 037cc60..32e89d7 100644
--- a/luni/src/main/java/java/io/StringBufferInputStream.java
+++ b/luni/src/main/java/java/io/StringBufferInputStream.java
@@ -60,12 +60,6 @@ public class StringBufferInputStream extends InputStream {
         count = str.length();
     }
 
-    /**
-     * Returns the number of bytes that are available before this stream will
-     * block.
-     *
-     * @return the number of bytes available before blocking.
-     */
     @Override
     public synchronized int available() {
         return count - pos;