Docs for Source and Sink.

okio/src/main/java/okio/BufferedSink.java

@@ -23,6 +23,7 @@ import java.io.OutputStream;
  * without a performance penalty.
  */
 public interface BufferedSink extends Sink {
+  /** Returns this sink's internal buffer. */
   OkBuffer buffer();
 
   BufferedSink write(ByteString byteString) throws IOException;
@@ -39,12 +40,16 @@ public interface BufferedSink extends Sink {
    */
   BufferedSink write(byte[] source, int offset, int byteCount) throws IOException;
 
+  /** Encodes {@code string} in UTF-8 and writes it to this sink. */
   BufferedSink writeUtf8(String string) throws IOException;
 
+  /** Writes byte to the end of this sink. */
   BufferedSink writeByte(int b) throws IOException;
 
+  /** Writes a Big-Endian short to the end of this sink. */
   BufferedSink writeShort(int s) throws IOException;
 
+  /** Writes a Big-Endian int to the end of this sink. */
   BufferedSink writeInt(int i) throws IOException;
 
   /** Writes complete segments to the sink. Like {@link #flush}, but weaker. */

okio/src/main/java/okio/BufferedSource.java

@@ -24,6 +24,7 @@ import java.io.InputStream;
  * buffering as much as necessary before consuming input.
  */
 public interface BufferedSource extends Source {
+  /** Returns this source's internal buffer. */
   OkBuffer buffer();
 
   /**

okio/src/main/java/okio/Sink.java

@@ -19,7 +19,33 @@ import java.io.Closeable;
 import java.io.IOException;
 
 /**
- * An alternative to OutputStream.
+ * Receives a stream of bytes. Use this interface to write data wherever it's
+ * needed: to the network, storage, or a buffer in memory. Sinks may be layered
+ * to transform received data, such as to compress, encrypt, throttle, or add
+ * protocol framing.
+ *
+ * <p>Most application code shouldn't operate on a sink directly, but rather
+ * {@link BufferedSink} which is both more efficient and more convenient. Use
+ * {@link Okio#buffer(Sink)} to wrap any sink with a buffer.
+ *
+ * <p>Sinks are easy to test: just use an {@link OkBuffer} in your tests, and
+ * read from it to confirm it received the data that was expected.
+ *
+ * <h3>Comparison with OutputStream</h3>
+ * This interface is functionally equivalent to {@link java.io.OutputStream}.
+ *
+ * <p>{@code OutputStream} requires multiple layers when emitted data is
+ * heterogeneous: a {@code DataOutputStream} for primitive values, a {@code
+ * BufferedOutputStream} for buffering, and {@code OutputStreamWriter} for
+ * charset encoding. This class uses {@code BufferedSink} for all of the above.
+ *
+ * <p>Sink is also easier to layer: there is no {@link
+ * java.io.OutputStream#write(int) single-byte write} method that is awkward to
+ * implement efficiently.
+ *
+ * <h3>Interop with OutputStream</h3>
+ * Use {@link Okio#sink} to adapt an {@code OutputStream} to a sink. Use {@link
+ * BufferedSink#outputStream} to adapt a sink to an {@code OutputStream}.
  */
 public interface Sink extends Closeable {
   /** Removes {@code byteCount} bytes from {@code source} and appends them to this. */

okio/src/main/java/okio/Source.java

@@ -19,7 +19,45 @@ import java.io.Closeable;
 import java.io.IOException;
 
 /**
- * An alternative to InputStream.
+ * Supplies a stream of bytes. Use this interface to read data from wherever
+ * it's located: from the network, storage, or a buffer in memory. Sources may
+ * be layered to transform supplied data, such as to decompress, decrypt, or
+ * remove protocol framing.
+ *
+ * <p>Most applications shouldn't operate on a source directly, but rather
+ * {@link BufferedSource} which is both more efficient and more convenient. Use
+ * {@link Okio#buffer(Source)} to wrap any source with a buffer.
+ *
+ * <p>Sources are easy to test: just use an {@link OkBuffer} in your tests, and
+ * fill it with the data your application is to read.
+ *
+ * <h3>Comparison with InputStream</h3>
+ * This interface is functionally equivalent to {@link java.io.InputStream}.
+ *
+ * <p>{@code InputStream} requires multiple layers when consumed data is
+ * heterogeneous: a {@code DataOutputStream} for primitive values, a {@code
+ * BufferedInputStream} for buffering, and {@code InputStreamReader} for
+ * strings. This class uses {@code BufferedSource} for all of the above.
+ *
+ * <p>Source avoids the impossible-to-implement {@link
+ * java.io.InputStream#available available()} method. Instead callers specify
+ * how many bytes they {@link BufferedSource#require require}.
+ *
+ * <p>Source omits the unsafe-to-compose {@link java.io.InputStream#mark mark
+ * and reset} state that's tracked by {@code InputStream}; callers instead just
+ * buffer what they need.
+ *
+ * <p>When implementing a source, you need not worry about the {@link
+ * java.io.InputStream#read single-byte read} method that is awkward to
+ * implement efficiently and that returns one of 257 possible values.
+ *
+ * <p>And source has a stronger {@code skip} method: {@link BufferedSource#skip}
+ * won't return prematurely.
+ *
+ * <h3>Interop with InputStream</h3>
+ * Use {@link Okio#source} to adapt an {@code InputStream} to a source. Use
+ * {@link BufferedSource#inputStream} to adapt a source to an {@code
+ * InputStream}.
  */
 public interface Source extends Closeable {
   /**