RFR JDK-8003258: BufferedReader.lines()

[Paul Sandoz]

On May 1, 2013, at 6:36 AM, Henry Jen <henry.jen at oracle.com> wrote:
> 
>> 
>>    /**
>>     * Returns a {@code Stream}, the elements of which are lines read from this
>>     * {@code BufferedReader}.  The {@link Stream} is lazily populated via
>>     * calls to {@link #readLine()}.
>>     *
>>     * <p>Each element consumed by the {@code Stream} caused a line to be
>>     * read from this {@code BufferedReader}. Since the {@code Stream} does
>>     * not necessarily consume all lines, it is possible to mix and use
>>     * different read methods on a {@code BufferedReader}. Each method will
>>     * simply pick up from where it was left on last read.
>>     *
>>     * <p>The reader must not be operated on during the execution of the terminal
>>     * stream operation. Otherwise, the result of the terminal stream operation is 
>>     * undefined
>>     *
>>     * <p>Noted that some terminal stream operations make no guarantee how many
>>     * element to be consumed. Therefore after execution of the terminal
>>     * stream operation there are no guarantees that the reader will be at a
>>     * specific position from which to read the next character or line.
>>     *

I don't think the first sentence of the above paragraph is necessary for normative stuff. I think it sufficient to state "After execution of the terminal operation there are... "

You could, if you wish, add an @apiNote providing further details as to why there are no such guarantees.

Paul.