Add CharSource.lines().

Also make a variety of javadoc tweaks and improvements.

Fixes google#2693.

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=149122377

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

@@ -16,6 +16,7 @@
 
 package com.google.common.io;
 
+import static com.google.common.collect.ImmutableList.toImmutableList;
 import static com.google.common.io.TestOption.CLOSE_THROWS;
 import static com.google.common.io.TestOption.OPEN_THROWS;
 import static com.google.common.io.TestOption.READ_THROWS;
@@ -33,6 +34,7 @@
 import java.io.Writer;
 import java.util.EnumSet;
 import java.util.List;
+import java.util.stream.Stream;
 import junit.framework.TestSuite;
 
 /**
@@ -57,6 +59,8 @@ public static TestSuite suite() {
 
   private static final String STRING = ASCII + I18N;
   private static final String LINES = "foo\nbar\r\nbaz\rsomething";
+  private static final ImmutableList<String> SPLIT_LINES =
+      ImmutableList.of("foo", "bar", "baz", "something");
 
   private TestCharSource source;
 
@@ -83,6 +87,21 @@ public void testOpenBufferedStream() throws IOException {
     assertEquals(STRING, writer.toString());
   }
 
+  public void testLines() throws IOException {
+    source = new TestCharSource(LINES);
+
+    ImmutableList<String> lines;
+    try (Stream<String> linesStream = source.lines()) {
+      assertTrue(source.wasStreamOpened());
+      assertFalse(source.wasStreamClosed());
+
+      lines = linesStream.collect(toImmutableList());
+    }
+
+    assertTrue(source.wasStreamClosed());
+    assertEquals(SPLIT_LINES, lines);
+  }
+
   public void testCopyTo_appendable() throws IOException {
     StringBuilder builder = new StringBuilder();
 

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

@@ -16,20 +16,22 @@
 
 package com.google.common.io;
 
-import static com.google.common.io.SourceSinkFactory.ByteSourceFactory;
-import static com.google.common.io.SourceSinkFactory.CharSourceFactory;
+import static com.google.common.collect.ImmutableList.toImmutableList;
 
 import com.google.common.base.Charsets;
 import com.google.common.base.Optional;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.Lists;
+import com.google.common.io.SourceSinkFactory.ByteSourceFactory;
+import com.google.common.io.SourceSinkFactory.CharSourceFactory;
 import java.io.BufferedReader;
 import java.io.IOException;
 import java.io.Reader;
 import java.io.StringWriter;
 import java.lang.reflect.Method;
 import java.util.List;
 import java.util.Map;
+import java.util.stream.Stream;
 import junit.framework.TestSuite;
 
 /**
@@ -122,6 +124,12 @@ public void testOpenBufferedStream() throws IOException {
     assertExpectedString(writer.toString());
   }
 
+  public void testLines() throws IOException {
+    try (Stream<String> lines = source.lines()) {
+      assertExpectedLines(lines.collect(toImmutableList()));
+    }
+  }
+
   public void testCopyTo_appendable() throws IOException {
     StringBuilder builder = new StringBuilder();
 

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

@@ -61,25 +61,25 @@ public CharSink asCharSink(Charset charset) {
   }
 
   /**
-   * Opens a new {@link OutputStream} for writing to this sink. This method should return a new,
+   * Opens a new {@link OutputStream} for writing to this sink. This method returns a new,
    * independent stream each time it is called.
    *
    * <p>The caller is responsible for ensuring that the returned stream is closed.
    *
-   * @throws IOException if an I/O error occurs in the process of opening the stream
+   * @throws IOException if an I/O error occurs while opening the stream
    */
   public abstract OutputStream openStream() throws IOException;
 
   /**
    * Opens a new buffered {@link OutputStream} for writing to this sink. The returned stream is not
    * required to be a {@link BufferedOutputStream} in order to allow implementations to simply
    * delegate to {@link #openStream()} when the stream returned by that method does not benefit from
-   * additional buffering (for example, a {@code ByteArrayOutputStream}). This method should return
-   * a new, independent stream each time it is called.
+   * additional buffering (for example, a {@code ByteArrayOutputStream}). This method returns a new,
+   * independent stream each time it is called.
    *
    * <p>The caller is responsible for ensuring that the returned stream is closed.
    *
-   * @throws IOException if an I/O error occurs in the process of opening the stream
+   * @throws IOException if an I/O error occurs while opening the stream
    * @since 15.0 (in 14.0 with return type {@link BufferedOutputStream})
    */
   public OutputStream openBufferedStream() throws IOException {
@@ -92,7 +92,7 @@ public OutputStream openBufferedStream() throws IOException {
   /**
    * Writes all the given bytes to this sink.
    *
-   * @throws IOException if an I/O occurs in the process of writing to this sink
+   * @throws IOException if an I/O occurs while writing to this sink
    */
   public void write(byte[] bytes) throws IOException {
     checkNotNull(bytes);
@@ -114,8 +114,7 @@ public void write(byte[] bytes) throws IOException {
    * {@code input}.
    *
    * @return the number of bytes written
-   * @throws IOException if an I/O occurs in the process of reading from {@code input} or writing to
-   *     this sink
+   * @throws IOException if an I/O occurs while reading from {@code input} or writing to this sink
    */
   @CanIgnoreReturnValue
   public long writeFrom(InputStream input) throws IOException {

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

@@ -80,25 +80,25 @@ public CharSource asCharSource(Charset charset) {
   }
 
   /**
-   * Opens a new {@link InputStream} for reading from this source. This method should return a new,
+   * Opens a new {@link InputStream} for reading from this source. This method returns a new,
    * independent stream each time it is called.
    *
    * <p>The caller is responsible for ensuring that the returned stream is closed.
    *
-   * @throws IOException if an I/O error occurs in the process of opening the stream
+   * @throws IOException if an I/O error occurs while opening the stream
    */
   public abstract InputStream openStream() throws IOException;
 
   /**
    * Opens a new buffered {@link InputStream} for reading from this source. The returned stream is
    * not required to be a {@link BufferedInputStream} in order to allow implementations to simply
    * delegate to {@link #openStream()} when the stream returned by that method does not benefit from
-   * additional buffering (for example, a {@code ByteArrayInputStream}). This method should return a
+   * additional buffering (for example, a {@code ByteArrayInputStream}). This method returns a
    * new, independent stream each time it is called.
    *
    * <p>The caller is responsible for ensuring that the returned stream is closed.
    *
-   * @throws IOException if an I/O error occurs in the process of opening the stream
+   * @throws IOException if an I/O error occurs while opening the stream
    * @since 15.0 (in 14.0 with return type {@link BufferedInputStream})
    */
   public InputStream openBufferedStream() throws IOException {
@@ -186,7 +186,7 @@ public Optional<Long> sizeIfKnown() {
    * <p>In either case, for mutable sources such as files, a subsequent read may return a different
    * number of bytes if the contents are changed.
    *
-   * @throws IOException if an I/O error occurs in the process of reading the size of this source
+   * @throws IOException if an I/O error occurs while reading the size of this source
    */
   public long size() throws IOException {
     Optional<Long> sizeIfKnown = sizeIfKnown();
@@ -233,8 +233,8 @@ private long countBySkipping(InputStream in) throws IOException {
    * {@code output}.
    *
    * @return the number of bytes copied
-   * @throws IOException if an I/O error occurs in the process of reading from this source or
-   *     writing to {@code output}
+   * @throws IOException if an I/O error occurs while reading from this source or writing to
+   *     {@code output}
    */
   @CanIgnoreReturnValue
   public long copyTo(OutputStream output) throws IOException {
@@ -255,8 +255,8 @@ public long copyTo(OutputStream output) throws IOException {
    * Copies the contents of this byte source to the given {@code ByteSink}.
    *
    * @return the number of bytes copied
-   * @throws IOException if an I/O error occurs in the process of reading from this source or
-   *     writing to {@code sink}
+   * @throws IOException if an I/O error occurs while reading from this source or writing to
+   *     {@code sink}
    */
   @CanIgnoreReturnValue
   public long copyTo(ByteSink sink) throws IOException {
@@ -277,7 +277,7 @@ public long copyTo(ByteSink sink) throws IOException {
   /**
    * Reads the full contents of this byte source as a byte array.
    *
-   * @throws IOException if an I/O error occurs in the process of reading from this source
+   * @throws IOException if an I/O error occurs while reading from this source
    */
   public byte[] read() throws IOException {
     Closer closer = Closer.create();
@@ -296,7 +296,7 @@ public byte[] read() throws IOException {
    * they are read. Stops when all bytes have been read or the consumer returns {@code false}.
    * Returns the result produced by the processor.
    *
-   * @throws IOException if an I/O error occurs in the process of reading from this source or if
+   * @throws IOException if an I/O error occurs while reading from this source or if
    *     {@code processor} throws an {@code IOException}
    * @since 16.0
    */
@@ -319,7 +319,7 @@ public <T> T read(ByteProcessor<T> processor) throws IOException {
   /**
    * Hashes the contents of this byte source using the given hash function.
    *
-   * @throws IOException if an I/O error occurs in the process of reading from this source
+   * @throws IOException if an I/O error occurs while reading from this source
    */
   public HashCode hash(HashFunction hashFunction) throws IOException {
     Hasher hasher = hashFunction.newHasher();
@@ -331,8 +331,7 @@ public HashCode hash(HashFunction hashFunction) throws IOException {
    * Checks that the contents of this byte source are equal to the contents of the given byte
    * source.
    *
-   * @throws IOException if an I/O error occurs in the process of reading from this source or
-   *     {@code other}
+   * @throws IOException if an I/O error occurs while reading from this source or {@code other}
    */
   public boolean contentEquals(ByteSource other) throws IOException {
     checkNotNull(other);
@@ -435,7 +434,7 @@ public static ByteSource empty() {
   /**
    * A char source that reads bytes from this source and decodes them as characters using a charset.
    */
-  private final class AsCharSource extends CharSource {
+  class AsCharSource extends CharSource {
 
     final Charset charset;
 

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

@@ -55,24 +55,24 @@ public abstract class CharSink {
   protected CharSink() {}
 
   /**
-   * Opens a new {@link Writer} for writing to this sink. This method should return a new,
-   * independent writer each time it is called.
+   * Opens a new {@link Writer} for writing to this sink. This method returns a new, independent
+   * writer each time it is called.
    *
    * <p>The caller is responsible for ensuring that the returned writer is closed.
    *
-   * @throws IOException if an I/O error occurs in the process of opening the writer
+   * @throws IOException if an I/O error occurs while opening the writer
    */
   public abstract Writer openStream() throws IOException;
 
   /**
    * Opens a new buffered {@link Writer} for writing to this sink. The returned stream is not
    * required to be a {@link BufferedWriter} in order to allow implementations to simply delegate to
    * {@link #openStream()} when the stream returned by that method does not benefit from additional
-   * buffering. This method should return a new, independent writer each time it is called.
+   * buffering. This method returns a new, independent writer each time it is called.
    *
    * <p>The caller is responsible for ensuring that the returned writer is closed.
    *
-   * @throws IOException if an I/O error occurs in the process of opening the writer
+   * @throws IOException if an I/O error occurs while opening the writer
    * @since 15.0 (in 14.0 with return type {@link BufferedWriter})
    */
   public Writer openBufferedStream() throws IOException {
@@ -85,7 +85,7 @@ public Writer openBufferedStream() throws IOException {
   /**
    * Writes the given character sequence to this sink.
    *
-   * @throws IOException if an I/O error in the process of writing to this sink
+   * @throws IOException if an I/O error while writing to this sink
    */
   public void write(CharSequence charSequence) throws IOException {
     checkNotNull(charSequence);
@@ -107,7 +107,7 @@ public void write(CharSequence charSequence) throws IOException {
    * the operating system's default line separator. This method is equivalent to
    * {@code writeLines(lines, System.getProperty("line.separator"))}.
    *
-   * @throws IOException if an I/O error occurs in the process of writing to this sink
+   * @throws IOException if an I/O error occurs while writing to this sink
    */
   public void writeLines(Iterable<? extends CharSequence> lines) throws IOException {
     writeLines(lines, System.getProperty("line.separator"));
@@ -117,7 +117,7 @@ public void writeLines(Iterable<? extends CharSequence> lines) throws IOExceptio
    * Writes the given lines of text to this sink with each line (including the last) terminated with
    * the given line separator.
    *
-   * @throws IOException if an I/O error occurs in the process of writing to this sink
+   * @throws IOException if an I/O error occurs while writing to this sink
    */
   public void writeLines(Iterable<? extends CharSequence> lines, String lineSeparator)
       throws IOException {
@@ -143,8 +143,8 @@ public void writeLines(Iterable<? extends CharSequence> lines, String lineSepara
    * Does not close {@code readable} if it is {@code Closeable}.
    *
    * @return the number of characters written
-   * @throws IOException if an I/O error occurs in the process of reading from {@code readable} or
-   *     writing to this sink
+   * @throws IOException if an I/O error occurs while reading from {@code readable} or writing to
+   *     this sink
    */
   @CanIgnoreReturnValue
   public long writeFrom(Readable readable) throws IOException {