improved java doc

guava-tests/test/com/google/common/io/LineBufferTest.java

@@ -16,6 +16,8 @@
 
 package com.google.common.io;
 
+import static com.google.common.collect.ImmutableList.toImmutableList;
+
 import com.google.common.base.Function;
 import com.google.common.collect.Lists;
 import java.io.BufferedReader;
@@ -26,7 +28,6 @@
 import java.nio.CharBuffer;
 import java.util.Arrays;
 import java.util.List;
-import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
 /**
@@ -76,10 +77,13 @@ public String apply(String value) {
  assertEquals(expectRead, readUsingJava(input, chunk));
  assertEquals(expectRead, readUsingReader(input, chunk, true));
  assertEquals(expectRead, readUsingReader(input, chunk, false));
- assertTrue(expectRead.containsAll(readUsingReaderGetLines(input, chunk, true)
- .collect(Collectors.toList())));
- assertTrue(expectRead.containsAll(readUsingReaderGetLines(input, chunk, false)
- .collect(Collectors.toList())));
+ try (Stream<String> linesStream = readUsingReaderGetLines(input, chunk, true)) {
+ assertTrue(expectRead.containsAll(linesStream.collect(toImmutableList())));
+ }
+
+ try (Stream<String> linesStream = readUsingReaderGetLines(input, chunk, false)) {
+ assertTrue(expectRead.containsAll(linesStream.collect(toImmutableList())));
+ }
  }
  }
 

guava/src/com/google/common/io/LineReader.java

@@ -21,6 +21,9 @@
 import com.google.common.annotations.GwtIncompatible;
 import com.google.common.collect.AbstractIterator;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import com.google.errorprone.annotations.MustBeClosed;
+
+import java.io.BufferedReader;
 import java.io.IOException;
 import java.io.Reader;
 import java.io.UncheckedIOException;
@@ -93,12 +96,31 @@ public String readLine() throws IOException {
  }
 
  /**
- * Returns a {@code Stream}, the elements of which are lines read from
- * this {@code LineReader}.
+ * Returns a {@code Stream}, the elements of which are lines read from this {@code LineReader}.
+ *
+ * <p>The returned stream is lazy and only reads from the source in the terminal operation. If an
+ * I/O error occurs while the stream is reading from the source or when the stream is closed, an
+ * {@link UncheckedIOException} is thrown.
+ *
+ * <p>Like {@link LineReader#readLine()}, this method reads a line of text. A line is
+ * considered to be terminated by any one of a line feed ({@code '\n'}), a carriage return
+ * ({@code '\r'}), or a carriage return followed immediately by a linefeed ({@code "\r\n"}).
+ *
+ * <p>The caller is responsible for ensuring that the returned stream is closed. For example:
+ *
+ * <pre>{@code
+ * try (Stream<String> lines = source.lines()) {
+ * lines.map(...)
+ * .filter(...)
+ * .forEach(...);
+ * }
+ * }</pre>
  *
  * @return a {@code Stream<String>} providing the lines of text
  * described by this {@code LineReader}
+ * @throws UncheckedIOException if an I/O error occurs.
  */
+ @MustBeClosed
  public Stream<String> lines() {
  AbstractIterator<String> iterator = new AbstractIterator<String>() {
  @CheckForNull