Merge pull request #375 from clue-labs/docs

Improve documentation and use fully-qualified class names throughout the documentation

Author: jsor

README.md

@@ -2,16 +2,15 @@
 
 namespace React\Http;
 
+use Psr\Http\Message\ResponseInterface;
+use React\EventLoop\LoopInterface;
+use React\Http\Io\MessageFactory;
 use React\Http\Io\Sender;
 use React\Http\Io\Transaction;
-use React\Http\Message\MessageFactory;
-use InvalidArgumentException;
-use Psr\Http\Message\RequestInterface;
-use Psr\Http\Message\UriInterface;
-use React\EventLoop\LoopInterface;
 use React\Promise\PromiseInterface;
 use React\Socket\ConnectorInterface;
 use React\Stream\ReadableStreamInterface;
+use InvalidArgumentException;
 
 /**
  * @final This class is final and shouldn't be extended as it is likely to be marked final in a future relase.
@@ -719,7 +718,7 @@ private function withOptions(array $options)
 
     /**
      * @param string                         $method
-     * @param string|UriInterface            $url
+     * @param string                         $url
      * @param array                          $headers
      * @param string|ReadableStreamInterface $contents
      * @return PromiseInterface<ResponseInterface,Exception>

src/Browser.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace React\Http\Message;
+namespace React\Http\Io;
 
 use Psr\Http\Message\StreamInterface;
 use Psr\Http\Message\UriInterface;

src/Message/MessageFactory.php src/Io/MessageFactory.phpsrc/Message/MessageFactory.php renamed to src/Io/MessageFactory.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace React\Http\Message;
+namespace React\Http\Io;
 
 use Evenement\EventEmitter;
 use Psr\Http\Message\StreamInterface;

src/Message/ReadableBodyStream.php src/Io/ReadableBodyStream.phpsrc/Message/ReadableBodyStream.php renamed to src/Io/ReadableBodyStream.php

@@ -2,7 +2,6 @@
 
 namespace React\Http\Io;
 
-use React\Http\Message\MessageFactory;
 use Psr\Http\Message\RequestInterface;
 use React\EventLoop\LoopInterface;
 use React\Http\Client\Client as HttpClient;

src/Io/Sender.php

@@ -2,12 +2,11 @@
 
 namespace React\Http\Io;
 
-use React\Http\Message\ResponseException;
-use React\Http\Message\MessageFactory;
 use Psr\Http\Message\RequestInterface;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\UriInterface;
 use React\EventLoop\LoopInterface;
+use React\Http\Message\ResponseException;
 use React\Promise\Deferred;
 use React\Promise\PromiseInterface;
 use React\Stream\ReadableStreamInterface;

src/Io/Transaction.php

@@ -25,10 +25,9 @@
  * which in turn extends the
  * [PSR-7 `MessageInterface`](https://www.php-fig.org/psr/psr-7/#31-psrhttpmessagemessageinterface).
  *
- * > Internally, this class extends the underlying `\RingCentral\Psr7\Response`
- *   class. The only difference is that this class will accept implemenations
- *   of ReactPHPs `ReadableStreamInterface` for the `$body` argument. This base
- *   class is considered an implementation detail that may change in the future.
+ * > Internally, this implementation builds on top of an existing incoming
+ *   response message and only adds required streaming support. This base class is
+ *   considered an implementation detail that may change in the future.
  *
  * @see \Psr\Http\Message\ResponseInterface
  */

src/Message/Response.php

@@ -6,7 +6,7 @@
 use Psr\Http\Message\ResponseInterface;
 
 /**
- * The `ResponseException` is an `Exception` sub-class that will be used to reject
+ * The `React\Http\Message\ResponseException` is an `Exception` sub-class that will be used to reject
  * a request promise if the remote server returns a non-success status code
  * (anything but 2xx or 3xx).
  * You can control this behavior via the [`withRejectErrorResponse()` method](#withrejecterrorresponse).
@@ -32,7 +32,7 @@ public function __construct(ResponseInterface $response, $message = null, $code
     }
 
     /**
-     * Access its underlying [`ResponseInterface`](#responseinterface) object.
+     * Access its underlying response object.
      *
      * @return ResponseInterface
      */

src/Message/ResponseException.php

@@ -29,10 +29,10 @@
  * than 10 handlers will be invoked at once:
  *
  * ```php
- * $server = new Server(
+ * $server = new React\Http\Server(
  *     $loop,
- *     new StreamingRequestMiddleware(),
- *     new LimitConcurrentRequestsMiddleware(10),
+ *     new React\Http\Middleware\StreamingRequestMiddleware(),
+ *     new React\Http\Middleware\LimitConcurrentRequestsMiddleware(10),
  *     $handler
  * );
  * ```
@@ -42,12 +42,12 @@
  * to limit the total number of requests that can be buffered at once:
  *
  * ```php
- * $server = new Server(
+ * $server = new React\Http\Server(
  *     $loop,
- *     new StreamingRequestMiddleware(),
- *     new LimitConcurrentRequestsMiddleware(100), // 100 concurrent buffering handlers
- *     new RequestBodyBufferMiddleware(2 * 1024 * 1024), // 2 MiB per request
- *     new RequestBodyParserMiddleware(),
+ *     new React\Http\Middleware\StreamingRequestMiddleware(),
+ *     new React\Http\Middleware\LimitConcurrentRequestsMiddleware(100), // 100 concurrent buffering handlers
+ *     new React\Http\Middleware\RequestBodyBufferMiddleware(2 * 1024 * 1024), // 2 MiB per request
+ *     new React\Http\Middleware\RequestBodyParserMiddleware(),
  *     $handler
  * );
  * ```
@@ -57,13 +57,13 @@
  * processes one request after another without any concurrency:
  *
  * ```php
- * $server = new Server(
+ * $server = new React\Http\Server(
  *     $loop,
- *     new StreamingRequestMiddleware(),
- *     new LimitConcurrentRequestsMiddleware(100), // 100 concurrent buffering handlers
- *     new RequestBodyBufferMiddleware(2 * 1024 * 1024), // 2 MiB per request
- *     new RequestBodyParserMiddleware(),
- *     new LimitConcurrentRequestsMiddleware(1), // only execute 1 handler (no concurrency)
+ *     new React\Http\Middleware\StreamingRequestMiddleware(),
+ *     new React\Http\Middleware\LimitConcurrentRequestsMiddleware(100), // 100 concurrent buffering handlers
+ *     new React\Http\Middleware\RequestBodyBufferMiddleware(2 * 1024 * 1024), // 2 MiB per request
+ *     new React\Http\Middleware\RequestBodyParserMiddleware(),
+ *     new React\Http\Middleware\LimitConcurrentRequestsMiddleware(1), // only execute 1 handler (no concurrency)
  *     $handler
  * );
  * ```

src/Middleware/LimitConcurrentRequestsMiddleware.php

@@ -14,7 +14,7 @@
 use React\Socket\ServerInterface;
 
 /**
- * The `Server` class is responsible for handling incoming connections and then
+ * The `React\Http\Server` class is responsible for handling incoming connections and then
  * processing each incoming HTTP request.
  *
  * When a complete HTTP request has been received, it will invoke the given
@@ -292,9 +292,9 @@ public function __construct(LoopInterface $loop)
      *
      * @param ServerInterface $socket
      */
-    public function listen(ServerInterface $server)
+    public function listen(ServerInterface $socket)
     {
-        $this->streamingServer->listen($server);
+        $this->streamingServer->listen($socket);
     }
 
     /**