Summary

Explicitly specify the behavior of Reader.skip(long) at end-of-stream.

Problem

The specification of the behavior of Reader.skip(long) at end-of-stream is insufficiently clear to some readers. For example some could think that -1 is returned if the method is invoked when the reader is already at end-of-stream.

Solution

Update the specification of Reader.read(long) and its overrides to specify clearly the behavior at end-of-stream.

Specification

A normative specdiff and a webrev are attached.

The text of Reader.skip() is updated and the subclasses inherit all or part of this text. In subclasses which have only

/**
 * {@inheritDoc}
 */

as the specification of skip(long), the method will no longer appear in the main method summary, but rather in the section "Methods declared in class java.io.Reader". This is the case for BufferedReader, LineNumberReader, and PushbackReader. The specifications of skip(long) in the other subclasses add some value however so their verbiage is not entirely inherited. FilterReader provides different text for its @throws clause for IllegalArgumentException, while CharArrayReader and StringReader provide their own verbiage except for their @param, @return, and @throws tags which inherit their respective descriptions.