Merge "Give InputStream/OutputStream decent documentation."

2 files changed, 49 insertions, 24 deletions

diff --git a/luni/src/main/java/java/io/InputStream.java b/luni/src/main/java/java/io/InputStream.java
index a363146..561e057 100644
--- a/luni/src/main/java/java/io/InputStream.java
+++ b/luni/src/main/java/java/io/InputStream.java
@@ -21,18 +21,33 @@ import java.util.Arrays;
 import libcore.io.Streams;
 
 /**
- * The base class for all input streams. An input stream is a means of reading
- * data from a source in a byte-wise manner.
- * <p>
- * Some input streams also support marking a position in the input stream and
- * returning to this position later. This abstract class does not provide a
- * fully working implementation, so it needs to be subclassed, and at least the
- * {@link #read()} method needs to be overridden. Overriding some of the
- * non-abstract methods is also often advised, since it might result in higher
- * efficiency.
- * <p>
- * Many specialized input streams for purposes like reading from a file already
- * exist in this package.
+ * A readable source of bytes.
+ *
+ * <p>Most clients will use input streams that read data from the file system
+ * ({@link FileInputStream}), the network ({@link java.net.Socket#getInputStream()}/{@link
+ * java.net.HttpURLConnection#getInputStream()}), or from an in-memory byte
+ * array ({@link ByteArrayInputStream}).
+ *
+ * <p>Use {@link InputStreamReader} to adapt a byte stream like this one into a
+ * character stream.
+ *
+ * <p>Most clients should wrap their input stream with {@link
+ * BufferedInputStream}. Callers that do only bulk reads may omit buffering.
+ *
+ * <p>Some implementations support marking a position in the input stream and
+ * resetting back to this position later. Implementations that don't return
+ * false from {@link #markSupported()} and throw an {@link IOException} when
+ * {@link #reset()} is called.
+ *
+ * <h3>Subclassing InputStream</h3>
+ * Subclasses that decorate another input stream should consider subclassing
+ * {@link FilterInputStream}, which delegates all calls to the source input
+ * stream.
+ *
+ * <p>All input stream subclasses should override <strong>both</strong> {@link
+ * #read() read()} and {@link #read(byte[],int,int) read(byte[],int,int)}. The
+ * three argument overload is necessary for bulk access to the data. This is
+ * much more efficient than byte-by-byte access.
  *
  * @see OutputStream
  */
diff --git a/luni/src/main/java/java/io/OutputStream.java b/luni/src/main/java/java/io/OutputStream.java
index 67c2b7b..1eeb069 100644
--- a/luni/src/main/java/java/io/OutputStream.java
+++ b/luni/src/main/java/java/io/OutputStream.java
@@ -20,18 +20,28 @@ package java.io;
 import java.util.Arrays;
 
 /**
- * The base class for all output streams. An output stream is a means of writing
- * data to a target in a byte-wise manner. Most output streams expect the
- * {@link #flush()} method to be called before closing the stream, to ensure all
- * data is actually written through.
- * <p>
- * This abstract class does not provide a fully working implementation, so it
- * needs to be subclassed, and at least the {@link #write(int)} method needs to
- * be overridden. Overriding some of the non-abstract methods is also often
- * advised, since it might result in higher efficiency.
- * <p>
- * Many specialized output streams for purposes like writing to a file already
- * exist in this package.
+ * A writable sink for bytes.
+ *
+ * <p>Most clients will use output streams that write data to the file system
+ * ({@link FileOutputStream}), the network ({@link java.net.Socket#getOutputStream()}/{@link
+ * java.net.HttpURLConnection#getOutputStream()}), or to an in-memory byte array
+ * ({@link ByteArrayOutputStream}).
+ *
+ * <p>Use {@link OutputStreamWriter} to adapt a byte stream like this one into a
+ * character stream.
+ *
+ * <p>Most clients should wrap their output stream with {@link
+ * BufferedOutputStream}. Callers that do only bulk writes may omit buffering.
+ *
+ * <h3>Subclassing OutputStream</h3>
+ * Subclasses that decorate another output stream should consider subclassing
+ * {@link FilterOutputStream}, which delegates all calls to the target output
+ * stream.
+ *
+ * <p>All output stream subclasses should override <strong>both</strong> {@link
+ * #write(int)} and {@link #write(byte[],int,int) write(byte[],int,int)}. The
+ * three argument overload is necessary for bulk access to the data. This is
+ * much more efficient than byte-by-byte access.
  *
  * @see InputStream
  */