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

18 files changed, 70 insertions, 158 deletions

diff --git a/archive/src/main/java/java/util/zip/InflaterInputStream.java b/archive/src/main/java/java/util/zip/InflaterInputStream.java
index d239a8a..8cd8cf2 100644
--- a/archive/src/main/java/java/util/zip/InflaterInputStream.java
+++ b/archive/src/main/java/java/util/zip/InflaterInputStream.java
@@ -279,8 +279,7 @@ public class InflaterInputStream extends FilterInputStream {
      * @return 0 if no further bytes are available. Otherwise returns 1,
      *         which suggests (but does not guarantee) that additional bytes are
      *         available.
-     * @throws IOException
-     *             If an error occurs.
+     * @throws IOException if this stream is closed or an error occurs
      */
     @Override
     public int available() throws IOException {
diff --git a/archive/src/main/java/java/util/zip/ZipInputStream.java b/archive/src/main/java/java/util/zip/ZipInputStream.java
index 554f5d5..e547612 100644
--- a/archive/src/main/java/java/util/zip/ZipInputStream.java
+++ b/archive/src/main/java/java/util/zip/ZipInputStream.java
@@ -385,18 +385,12 @@ public class ZipInputStream extends InflaterInputStream implements ZipConstants
         return skipped;
     }
 
-    /**
-     * Returns 0 if the {@code EOF} has been reached, otherwise returns 1.
-     *
-     * @return 0 after {@code EOF} of current entry, 1 otherwise.
-     * @throws IOException
-     *             if an IOException occurs.
-     */
     @Override
     public int available() throws IOException {
         if (closed) {
             throw new IOException(Messages.getString("archive.1E")); //$NON-NLS-1$
         }
+        // The InflaterInputStream contract says we must only return 0 or 1.
         return (currentEntry == null || inRead < currentEntry.size) ? 1 : 0;
     }
 
diff --git a/crypto/src/main/java/javax/crypto/CipherInputStream.java b/crypto/src/main/java/javax/crypto/CipherInputStream.java
index b2c626d..fb1ef27 100644
--- a/crypto/src/main/java/javax/crypto/CipherInputStream.java
+++ b/crypto/src/main/java/javax/crypto/CipherInputStream.java
@@ -185,13 +185,6 @@ public class CipherInputStream extends FilterInputStream {
         return i;
     }
 
-    /**
-     * Returns the number of bytes available without blocking.
-     *
-     * @return the number of bytes available, currently zero.
-     * @throws IOException
-     *             if an error occurs
-     */
     @Override
     public int available() throws IOException {
         return 0;
@@ -227,4 +220,3 @@ public class CipherInputStream extends FilterInputStream {
         return false;
     }
 }
-
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;
diff --git a/security/src/main/java/org/apache/harmony/security/provider/cert/X509CertFactoryImpl.java b/security/src/main/java/org/apache/harmony/security/provider/cert/X509CertFactoryImpl.java
index f0e47d9..cc175df 100644
--- a/security/src/main/java/org/apache/harmony/security/provider/cert/X509CertFactoryImpl.java
+++ b/security/src/main/java/org/apache/harmony/security/provider/cert/X509CertFactoryImpl.java
@@ -800,26 +800,17 @@ public class X509CertFactoryImpl extends CertificateFactorySpi {
             this.inStream = inStream;
         }
 
-        /**
-         * @see java.io.InputStream#available()
-         * method documentation for more info
-         */
+        @Override
         public int available() throws IOException {
             return (bar - pos) + inStream.available();
         }
 
-        /**
-         * @see java.io.InputStream#close()
-         * method documentation for more info
-         */
+        @Override
         public void close() throws IOException {
             inStream.close();
         }
 
-        /**
-         * @see java.io.InputStream#mark(int readlimit)
-         * method documentation for more info
-         */
+        @Override
         public void mark(int readlimit) {
             if (pos < 0) {
                 pos = 0;
@@ -830,10 +821,7 @@ public class X509CertFactoryImpl extends CertificateFactorySpi {
             }
         }
 
-        /**
-         * @see java.io.InputStream#markSupported()
-         * method documentation for more info
-         */
+        @Override
         public boolean markSupported() {
             return true;
         }
@@ -881,18 +869,12 @@ public class X509CertFactoryImpl extends CertificateFactorySpi {
             return inStream.read();
         }
 
-        /**
-         * @see java.io.InputStream#read(byte[] b)
-         * method documentation for more info
-         */
+        @Override
         public int read(byte[] b) throws IOException {
             return read(b, 0, b.length);
         }
 
-        /**
-         * @see java.io.InputStream#read(byte[] b, int off, int len)
-         * method documentation for more info
-         */
+        @Override
         public int read(byte[] b, int off, int len) throws IOException {
             int read_b;
             int i;
@@ -905,10 +887,7 @@ public class X509CertFactoryImpl extends CertificateFactorySpi {
             return i;
         }
 
-        /**
-         * @see java.io.InputStream#reset()
-         * method documentation for more info
-         */
+        @Override
         public void reset() throws IOException {
             if (pos >= 0) {
                 pos = (end + 1) % BUFF_SIZE;
@@ -918,10 +897,7 @@ public class X509CertFactoryImpl extends CertificateFactorySpi {
             }
         }
 
-        /**
-         * @see java.io.InputStream#skip(long n)
-         * method documentation for more info
-         */
+        @Override
         public long skip(long n) throws IOException {
             if (pos >= 0) {
                 long i = 0;
@@ -939,6 +915,3 @@ public class X509CertFactoryImpl extends CertificateFactorySpi {
         }
     }
 }
-
-
-
diff --git a/sql/src/main/java/SQLite/Blob.java b/sql/src/main/java/SQLite/Blob.java
index 3de9f8a..16fecf1 100644
--- a/sql/src/main/java/SQLite/Blob.java
+++ b/sql/src/main/java/SQLite/Blob.java
@@ -30,11 +30,7 @@ class BlobR extends InputStream {
     this.pos = 0;
     }
 
-    /**
-     * Return number of available bytes for reading.
-     * @return available input bytes
-     */
-
+    @Override
     public int available() throws IOException {
     int ret = blob.size - pos;
     return (ret < 0) ? 0 : ret;
diff --git a/x-net/src/main/java/org/apache/harmony/xnet/provider/jsse/SSLBufferedInput.java b/x-net/src/main/java/org/apache/harmony/xnet/provider/jsse/SSLBufferedInput.java
index a150470..31bb681 100644
--- a/x-net/src/main/java/org/apache/harmony/xnet/provider/jsse/SSLBufferedInput.java
+++ b/x-net/src/main/java/org/apache/harmony/xnet/provider/jsse/SSLBufferedInput.java
@@ -49,9 +49,6 @@ public class SSLBufferedInput extends SSLInputStream {
         this.in = in;
     }
 
-    /**
-     * Returns the number of bytes available for reading.
-     */
     @Override
     public int available() throws IOException {
         // in assumption that the buffer has been set
@@ -78,4 +75,3 @@ public class SSLBufferedInput extends SSLInputStream {
         return bytik;
     }
 }
-
diff --git a/x-net/src/main/java/org/apache/harmony/xnet/provider/jsse/SSLInputStream.java b/x-net/src/main/java/org/apache/harmony/xnet/provider/jsse/SSLInputStream.java
index 507e14f..b2501a7 100644
--- a/x-net/src/main/java/org/apache/harmony/xnet/provider/jsse/SSLInputStream.java
+++ b/x-net/src/main/java/org/apache/harmony/xnet/provider/jsse/SSLInputStream.java
@@ -29,9 +29,6 @@ import java.io.InputStream;
  */
 public abstract class SSLInputStream extends InputStream {
 
-    /**
-     * @see java.io.InputStream#available()
-     */
     @Override
     public abstract int available() throws IOException;
 
@@ -48,9 +45,6 @@ public abstract class SSLInputStream extends InputStream {
     @Override
     public abstract int read() throws IOException;
 
-    /**
-     * @see java.io.InputStream#skip(long)
-     */
     @Override
     public long skip(long n) throws IOException {
         long skept = n;
@@ -115,9 +109,6 @@ public abstract class SSLInputStream extends InputStream {
         return res;
     }
 
-    /**
-     * @see java.io.InputStream#read(byte[],int,int)
-     */
     @Override
     public int read(byte[] b, int off, int len) throws IOException {
         int read_b;