Mark internal APIs as internal or private

README.md

@@ -25,7 +25,7 @@ $loop = React\EventLoop\Factory::create();
 $socket = new React\Socket\Server(8080, $loop);
 
 $http = new React\Http\Server($socket);
-$http->on('request', function ($request, $response) {
+$http->on('request', function (Request $request, Response $response) {
     $response->writeHead(200, array('Content-Type' => 'text/plain'));
     $response->end("Hello World!\n");
 });
@@ -39,7 +39,30 @@ See also the [examples](examples).
 
 ### Server
 
-See the above usage example and the class outline for details.
+The `Server` class is responsible for handling incoming connections and then
+emit a `request` event for each incoming HTTP request.
+
+It attaches itself to an instance of `React\Socket\ServerInterface` which
+emits underlying streaming connections in order to then parse incoming data
+as HTTP:
+
+```php
+$socket = new React\Socket\Server(8080, $loop);
+
+$http = new React\Http\Server($socket);
+```
+
+For each incoming connection, it emits a `request` event with the respective
+[`Request`](#request) and [`Response`](#response) objects:
+
+```php
+$http->on('request', function (Request $request, Response $response) {
+    $response->writeHead(200, array('Content-Type' => 'text/plain'));
+    $response->end("Hello World!\n");
+});
+```
+
+See also [`Request`](#request) and [`Response`](#response) for more details.
 
 ### Request
 
@@ -48,6 +71,9 @@ and contains meta data which was parsed from the request headers.
 
 It implements the `ReadableStreamInterface`.
 
+The constructor is internal, you SHOULD NOT call this yourself.
+The `Server` is responsible for emitting `Request` and `Response` objects.
+
 See the above usage example and the class outline for details.
 
 #### getHeaders()
@@ -101,6 +127,9 @@ The `Response` class is responsible for streaming the outgoing response body.
 
 It implements the `WritableStreamInterface`.
 
+The constructor is internal, you SHOULD NOT call this yourself.
+The `Server` is responsible for emitting `Request` and `Response` objects.
+
 See the above usage example and the class outline for details.
 
 #### writeContinue()

src/Request.php

@@ -7,6 +7,20 @@
 use React\Stream\WritableStreamInterface;
 use React\Stream\Util;
 
+/**
+ * The `Request` class is responsible for streaming the incoming request body
+ * and contains meta data which was parsed from the request headers.
+ *
+ * It implements the `ReadableStreamInterface`.
+ *
+ * The constructor is internal, you SHOULD NOT call this yourself.
+ * The `Server` is responsible for emitting `Request` and `Response` objects.
+ *
+ * See the usage examples and the class outline for details.
+ *
+ * @see ReadableStreamInterface
+ * @see Server
+ */
 class Request extends EventEmitter implements ReadableStreamInterface
 {
     private $readable = true;
@@ -19,6 +33,15 @@ class Request extends EventEmitter implements ReadableStreamInterface
     // metadata, implicitly added externally
     public $remoteAddress;
 
+    /**
+     * The constructor is internal, you SHOULD NOT call this yourself.
+     *
+     * The `Server` is responsible for emitting `Request` and `Response` objects.
+     *
+     * Constructor parameters may change at any time.
+     *
+     * @internal
+     */
     public function __construct($method, $path, $query = array(), $httpVersion = '1.1', $headers = array())
     {
         $this->method = $method;

src/RequestHeaderParser.php

@@ -9,6 +9,8 @@
 /**
  * @event headers
  * @event error
+ *
+ * @internal
  */
 class RequestHeaderParser extends EventEmitter
 {
@@ -43,13 +45,13 @@ public function feed($data)
         }
     }
 
-    protected function parseAndEmitRequest()
+    private function parseAndEmitRequest()
     {
         list($request, $bodyBuffer) = $this->parseRequest($this->buffer);
         $this->emit('headers', array($request, $bodyBuffer));
     }
 
-    public function parseRequest($data)
+    private function parseRequest($data)
     {
         list($headers, $bodyBuffer) = explode("\r\n\r\n", $data, 2);
 

src/Response.php

@@ -6,6 +6,19 @@
 use React\Socket\ConnectionInterface;
 use React\Stream\WritableStreamInterface;
 
+/**
+ * The `Response` class is responsible for streaming the outgoing response body.
+ *
+ * It implements the `WritableStreamInterface`.
+ *
+ * The constructor is internal, you SHOULD NOT call this yourself.
+ * The `Server` is responsible for emitting `Request` and `Response` objects.
+ *
+ * See the usage examples and the class outline for details.
+ *
+ * @see WritableStreamInterface
+ * @see Server
+ */
 class Response extends EventEmitter implements WritableStreamInterface
 {
     private $closed = false;
@@ -14,6 +27,15 @@ class Response extends EventEmitter implements WritableStreamInterface
     private $headWritten = false;
     private $chunkedEncoding = true;
 
+    /**
+     * The constructor is internal, you SHOULD NOT call this yourself.
+     *
+     * The `Server` is responsible for emitting `Request` and `Response` objects.
+     *
+     * Constructor parameters may change at any time.
+     *
+     * @internal
+     */
     public function __construct(ConnectionInterface $conn)
     {
         $this->conn = $conn;

src/ResponseCodes.php

@@ -4,6 +4,8 @@
 
 /**
  * This is copy-pasted from Symfony2's Response class
+ *
+ * @internal
  */
 class ResponseCodes
 {

src/Server.php

@@ -6,11 +6,50 @@
 use React\Socket\ServerInterface as SocketServerInterface;
 use React\Socket\ConnectionInterface;
 
-/** @event request */
+/**
+ * The `Server` class is responsible for handling incoming connections and then
+ * emit a `request` event for each incoming HTTP request.
+ *
+ * ```php
+ * $socket = new React\Socket\Server(8080, $loop);
+ *
+ * $http = new React\Http\Server($socket);
+ * ```
+ *
+ * For each incoming connection, it emits a `request` event with the respective
+ * [`Request`](#request) and [`Response`](#response) objects:
+ *
+ * ```php
+ * $http->on('request', function (Request $request, Response $response) {
+ *     $response->writeHead(200, array('Content-Type' => 'text/plain'));
+ *     $response->end("Hello World!\n");
+ * });
+ * ```
+ *
+ * See also [`Request`](#request) and [`Response`](#response) for more details.
+ *
+ * @see Request
+ * @see Response
+ */
 class Server extends EventEmitter
 {
     private $io;
 
+    /**
+     * Creates a HTTP server that accepts connections from the given socket.
+     *
+     * It attaches itself to an instance of `React\Socket\ServerInterface` which
+     * emits underlying streaming connections in order to then parse incoming data
+     * as HTTP:
+     *
+     * ```php
+     * $socket = new React\Socket\Server(8080, $loop);
+     *
+     * $http = new React\Http\Server($socket);
+     * ```
+     *
+     * @param \React\Socket\ServerInterface $io
+     */
     public function __construct(SocketServerInterface $io)
     {
         $this->io = $io;
@@ -54,6 +93,7 @@ public function __construct(SocketServerInterface $io)
         });
     }
 
+    /** @internal */
     public function handleRequest(ConnectionInterface $conn, Request $request, $bodyBuffer)
     {
         $response = new Response($conn);