src/share/classes/java/io/BufferedReader.java

rev 7267 : [mq]: nio.diff

@@ -527,23 +527,31 @@
             }
         }
     }
 
     /**
-     * Returns a {@code Stream} describing lines read from this {@code
-     * BufferedReader}.  The {@link Stream} is lazily populated via calls to
-     * {@link #readLine()}.
-     * <p>
-     * If an {@link IOException} is thrown when accessing the underlying {@code
-     * BufferedReader}, it is wrapped in an {@link UncheckedIOException} which
-     * will be thrown from the {@code Stream} method that caused the read to
-     * take place.
+     * Returns a {@code Stream}, the elemtns of which are lines read from this
+     * {@code BufferedReader}.  The {@link Stream} is lazily populated via
+     * calls to {@link #readLine()}.
      *
-     * @since 1.8
+     * <p> Each element consumed by the {@code Stream} caused a line to be
+     * read from this {@code BufferedReader}. Since the {@code Stream} does
+     * not necessary 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> If an {@link IOException} is thrown when accessing the underlying
+     * {@code BufferedReader}, it is wrapped in an {@link
+     * UncheckedIOException} which will be thrown from the {@code Stream}
+     * method that caused the read to take place. For example, when trying to
+     * read from the {@code Stream} after the {@code BufferedReader} is
+     * closed, will throw an {@code UnchecheckedIOException}.
      *
-     * @return a {@code Stream&lt;String&gt;} containing the lines of text
+     * @return a {@code Stream<String>} containing the lines of text
      *         described by this {@code BufferedReader}
+     *
+     * @since 1.8
      */
     public Stream<String> lines() {
         Iterator<String> iter = new Iterator<String>() {
             String nextLine = null;