RFR: 8247918: Clarify Reader.skip behavior for end of stream [v2]

[Roger Riggs]

On Fri, 12 Feb 2021 01:18:53 GMT, Brian Burkhalter <bpb at openjdk.org> wrote:

>> Please review this clarification of the specification of the method `skip(long)` in `java.io.Reader` and its subclasses. Specifically, the behavior of the method is made clear for the case when the `Reader` is already at the end of its stream when the method is invoked. A corresponding CSR will be filed. Also, the change includes an update to an existing test in order to verify that the specification change reflects actual behavior.
>
> Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:
> 
>   8247918: Change'ns' to 'n' in the skip doc

The use of @ inheritdoc causes some unexpected changes in the javadoc, dropping the skip method from several classes.

src/java.base/share/classes/java/io/StringReader.java line 108:

> 106: 
> 107:     /**
> 108:      * {@inheritDoc}

Using inheritDoc for the exceptions adds several new and irrelevant impossible causes to the javadoc.
" This method will block until some characters are available", etc.

src/java.base/share/classes/java/io/PushbackReader.java line 257:

> 255: 
> 256:     /**
> 257:      * {@inheritDoc}

This appears to make the skip method disappear from the PushbackReader javadoc
and only show up as a method declared in FilterReader.

src/java.base/share/classes/java/io/LineNumberReader.java line 270:

> 268: 
> 269:     /**
> 270:      * {@inheritDoc}

This appears to make the skip method disappear from the LineNumberReader javadoc
and only show up as a method declared in Reader.

src/java.base/share/classes/java/io/CharArrayReader.java line 149:

> 147: 
> 148:     /**
> 149:      * {@inheritDoc}

Using inheritDoc for the exceptions adds several new and irrelevant impossible causes to the javadoc.
" This method will block until some characters are available", etc.
It also drops the existing "If the stream is closed" condition on @ throws IOException.

src/java.base/share/classes/java/io/BufferedReader.java line 400:

> 398: 
> 399:     /**
> 400:      * {@inheritDoc}

This appears to make the skip method disappear from the BufferedReader javadoc
and only show up as a method declared in Reader.

-------------

PR: https://git.openjdk.java.net/jdk/pull/2274