Clean up specifications of java.io.Reader.read(char[],int,int) in subclass overrides

Summary

This change proposes to use {@inheritDoc} to improve consistency of the specification of Reader.read(char[],in,in) in java.io.Reader and its subclasses.

Problem

In the various specifications of read(char[],in,in) in Reader and its subclasses some verbiage is replicated and subject to divergence in the absence of using {@inheritdoc}.

Solution

Minimize verbiage duplication by more use of {@inheritdoc}.

Specification

A normative specdiff is attached; the remainder of this section is informative.

The substantive changes actually visible in the javadoc are as follows:

BufferedReader, FileReader

No change.

CharArrayReader, FilterReader, StringReader

Add as second paragraph:

If len is zero, then no characters are read and 0 is returned; otherwise, there is an attempt to read at least one character. If no character is available because the stream is at its end, the value -1 is returned; otherwise, at least one character is read and stored into cbuf.

InputStreamReader

Append to first paragraph:

This method will block until some input is available, an I/O error occurs, or the end of the stream is reached.

Add as second paragraph:

If len is zero, then no characters are read and 0 is returned; otherwise, there is an attempt to read at least one character. If no character is available because the stream is at its end, the value -1 is returned; otherwise, at least one character is read and stored into cbuf.

LineNumberReader

Specification is changed to:

Reads characters into a portion of an array. This method will block until some input is available, an I/O error occurs, or the end of the stream is reached.

If len is zero, then no characters are read and 0 is returned; otherwise, there is an attempt to read at least one character. If no character is available because the stream is at its end, the value -1 is returned; otherwise, at least one character is read and stored into cbuf. Line terminators are compressed into single newline ('\n') characters. The current line number is incremented whenever a line terminator is read, or when the end of the stream is reached and the last character in the stream is not a line terminator.

PipedReader

Specification is changed to:

Reads characters into a portion of an array. This method will block until some input is available, an I/O error occurs, or the end of the stream is reached.

If len is zero, then no characters are read and 0 is returned; otherwise, there is an attempt to read at least one character. If no character is available because the stream is at its end, the value -1 is returned; otherwise, at least one character is read and stored into cbuf. Fewer than len characters will be read if len exceeds the pipe's buffer size.

PushbackReader

Specification no longer appears in the main method summary but rather under Methods declared in class java.io.FilterReader.