JDK 9 RFR of JDK-8136738: InputStream documentation for IOException in skip() is unclear or incorrect

[Pavel Rappo]

Hi Brian,

> On 2 Jun 2016, at 22:48, Brian Burkhalter <brian.burkhalter at oracle.com> wrote:
> 
> Please review at your convenience this API doc-only change:
> 
> Issue:	https://bugs.openjdk.java.net/browse/JDK-8136738
> Patch:	http://cr.openjdk.java.net/~bpb/8136738/webrev.00/
> 
> Summary:
> 
> Try to make the specification of InputStream.skip() slightly more precise.
> 
> Thanks,
> 
> Brian

This looks good. 

I have a minor question though:

--- a/src/java.base/share/classes/java/io/InputStream.java
+++ b/src/java.base/share/classes/java/io/InputStream.java

-     * @exception  IOException  if the stream does not support seek,
-     *                          or if some other I/O error occurs.
+     * @throws     IOException  if an I/O error occurs, such as attempting to
+     *             seek to a negative position in a seek-based implementation.

Do we need to mention (even as an example) a case of passing a negative integer
position to `seek` function?

The only place where I've found this happens is in java.io.RandomAccessFile#seek

public void seek(long pos) throws IOException {
    if (pos < 0) {
        throw new IOException("Negative seek offset");
    } else {
        seek0(pos);
    }
}

But this class is not even in the InputStream hierarchy. But even if someone
decides to use seek, can't they choose some other strategy of dealing with
negative arguments?

Thanks,
-Pavel