Consistent event semantics for duplex streams

Author: clue

README.md

@@ -32,6 +32,7 @@ descriptor based implementation with an in-memory write buffer.
     * [write()](#write)
     * [end()](#end)
     * [close()](#close-1)
+  * [DuplexStreamInterface](#duplexstreaminterface)
 * [Usage](#usage)
 * [Install](#install)
 
@@ -672,6 +673,23 @@ how the readable side of the stream also implements a `close()` method.
 In other words, after calling this method, the stream MUST switch into
 non-writable AND non-readable mode, see also `isReadable()`.
 
+### DuplexStreamInterface
+
+The `DuplexStreamInterface` is responsible for providing an interface for
+duplex streams (both readable and writable).
+
+It builds on top of the existing interfaces for readable and writable streams
+and follows the exact same method and event semantics.
+If you're new to this concept, you should look into the
+`ReadableStreamInterface` and `WritableStreamInterface` first.
+
+Besides defining a few methods, this interface also implements the
+`EventEmitterInterface` which allows you to react to the same events defined
+on the `ReadbleStreamInterface` and `WritableStreamInterface`.
+
+See also [`ReadableStreamInterface`](#readablestreaminterface) and
+[`WritableStreamInterface`](#writablestreaminterface) for more details.
+
 ## Usage
 ```php
     $loop = React\EventLoop\Factory::create();

src/DuplexStreamInterface.php

@@ -2,6 +2,22 @@
 
 namespace React\Stream;
 
+/**
+ * The `DuplexStreamInterface` is responsible for providing an interface for
+ * duplex streams (both readable and writable).
+ *
+ * It builds on top of the existing interfaces for readable and writable streams
+ * and follows the exact same method and event semantics.
+ * If you're new to this concept, you should look into the
+ * `ReadableStreamInterface` and `WritableStreamInterface` first.
+ *
+ * Besides defining a few methods, this interface also implements the
+ * `EventEmitterInterface` which allows you to react to the same events defined
+ * on the `ReadbleStreamInterface` and `WritableStreamInterface`.
+ *
+ * @see ReadableStreamInterface
+ * @see WritableStreamInterface
+ */
 interface DuplexStreamInterface extends ReadableStreamInterface, WritableStreamInterface
 {
 }