Update comments and documentation for Dispatcher and related classes

src/Dispatching/DispatchStack.php

@@ -54,8 +54,11 @@ class DispatchStack implements DispatchStackInterface
      * @param callable $next
      * @return ResponseInterface
      */
-    public function __invoke(ServerRequestInterface $request, ResponseInterface $response, $next)
-    {
+    public function __invoke(
+        ServerRequestInterface $request,
+        ResponseInterface $response,
+        $next
+    ) {
         $dispatcher = $this->dispatcher;
 
         // This flag will be set to true when the last middleware calls $next.
@@ -70,9 +73,9 @@ class DispatchStack implements DispatchStackInterface
 
         // Create a chain of callables.
         //
-        // Each callable wil take $request and $response parameters, and will
-        // contain a dispatcher, the associated middleware, and a $next
-        // that is the links to the next middleware in the chain.
+        // Each callable will take $request and $response parameters, and will
+        // contain a dispatcher, the associated middleware, and a $next function
+        // that serves as the link to the next middleware in the chain.
         foreach (array_reverse($this->stack) as $middleware) {
             $chain = function ($request, $response) use ($dispatcher, $middleware, $chain) {
                 return $dispatcher->dispatch($middleware, $request, $response, $chain);

src/Dispatching/DispatchStackInterface.php

@@ -17,7 +17,7 @@ interface DispatchStackInterface extends MiddlewareInterface
      * This method MUST preserve the order in which middleware are added.
      *
      * @param mixed $middleware Middleware to dispatch in sequence
-     * @return self
+     * @return static
      */
     public function add($middleware);
 
@@ -48,5 +48,9 @@ interface DispatchStackInterface extends MiddlewareInterface
      * @param callable $next
      * @return ResponseInterface
      */
-    public function __invoke(ServerRequestInterface $request, ResponseInterface $response, $next);
+    public function __invoke(
+        ServerRequestInterface $request,
+        ResponseInterface $response,
+        $next
+    );
 }

src/Dispatching/Dispatcher.php

@@ -7,9 +7,31 @@ use Psr\Http\Message\ServerRequestInterface;
 use Psr\Http\Server\MiddlewareInterface;
 use Psr\Http\Server\RequestHandlerInterface;
 
+/**
+ * Dispatches handlers and middleware
+ */
 class Dispatcher implements DispatcherInterface
 {
     /**
+     * Dispatch a handler or middleware and return the response.
+     *
+     * Dispatcher can dispatch any of the following:
+     *   - An instance implementing one of these interfaces:
+     *     - Psr\Http\Server\RequestHandlerInterface
+     *     - Psr\Http\Server\MiddlewareInterface
+     *     - WellRESTed\MiddlewareInterface
+     *     - Psr\Http\Message\ResponseInterface
+     *   - A string containing the fully qualified class name of a class
+     *        implementing one of the interfaces listed above.
+     *   - A callable that returns an instance implementing one of the
+     *       interfaces listed above.
+     *   - A callable with a signature matching the signature of
+     *       WellRESTed\MiddlewareInterface::__invoke
+     *   - An array containing any of the items in this list.
+     *
+     * When Dispatcher receives a $dispatchable that is not of a type it
+     * can dispatch, it throws a DispatchException.
+     *
      * @param mixed $dispatchable
      * @param ServerRequestInterface $request
      * @param ResponseInterface $response
@@ -41,7 +63,7 @@ class Dispatcher implements DispatcherInterface
         } elseif ($dispatchable instanceof ResponseInterface) {
             return $dispatchable;
         } else {
-            throw new DispatchException("Unable to dispatch middleware.");
+            throw new DispatchException('Unable to dispatch middleware.');
         }
     }
 

src/Dispatching/DispatcherInterface.php

@@ -6,38 +6,47 @@ use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
 
 /**
- * Dispatches middleware
+ * Dispatches handlers and middleware
  */
 interface DispatcherInterface
 {
     /**
-     * Dispatch middleware and return the response.
+     * Dispatch a handler or middleware and return the response.
      *
-     * This method MUST pass $request, $response, and $next to the middleware
-     * to be dispatched.
-     *
-     * $middleware comes in a number of varieties (e.g., instance, string,
-     * callable). DispatcherInterface interface exist to unpack the middleware
-     * and dispatch it.
+     * Dispatchables (middleware and handlers) comes in a number of varieties
+     * (e.g., instance, string, callable). DispatcherInterface interface unpacks
+     * the dispatchable and dispatches it.
      *
      * Implementations MUST be able to dispatch the following:
-     * - An instance implementing MiddlewareInterface
+     *   - An instance implementing one of these interfaces:
+     *     - Psr\Http\Server\RequestHandlerInterface
+     *     - Psr\Http\Server\MiddlewareInterface
+     *     - WellRESTed\MiddlewareInterface
+     *     - Psr\Http\Message\ResponseInterface
      *   - A string containing the fully qualified class name of a class
-     *        implementing MiddlewareInterface
-     * - A callable that returns an instance implementing MiddlewareInterface
-     * - A callable with a signature matching MiddlewareInterface::__invoke
+     *        implementing one of the interfaces listed above.
+     *   - A callable that returns an instance implementing one of the
+     *       interfaces listed above.
+     *   - A callable with a signature matching the signature of
+     *       WellRESTed\MiddlewareInterface::__invoke
+     *   - An array containing any of the items in this list.
      *
      * Implementation MAY dispatch other types of middleware.
      *
-     * When an implementation receives a $middleware that is not of a type it can
-     * dispatch, it MUST throw a DispatchException.
+     * When an implementation receives a $dispatchable that is not of a type it
+     * can dispatch, it MUST throw a DispatchException.
      *
-     * @param mixed $middleware
+     * @param mixed $dispatchable
      * @param ServerRequestInterface $request
      * @param ResponseInterface $response
      * @param callable $next
      * @return ResponseInterface
      * @throws DispatchException Unable to dispatch $middleware
      */
-    public function dispatch($middleware, ServerRequestInterface $request, ResponseInterface $response, $next);
+    public function dispatch(
+        $dispatchable,
+        ServerRequestInterface $request,
+        ResponseInterface $response,
+        $next
+    );
 }

test/tests/unit/Transmission/TransmitterTest.php

@@ -25,7 +25,7 @@ class TransmitterTest extends TestCase
         $this->request = (new ServerRequest())
             ->withMethod("HEAD");
 
-        $this->body = $this->prophesize('\Psr\Http\Message\StreamInterface');
+        $this->body = $this->prophesize(StreamInterface::class);
         $this->body->isReadable()->willReturn(false);
         $this->body->getSize()->willReturn(1024);
         /** @var StreamInterface $stream */
@@ -36,12 +36,6 @@ class TransmitterTest extends TestCase
             ->withBody($stream);
     }
 
-    public function testCreatesInstance()
-    {
-        $transmitter = new Transmitter();
-        $this->assertNotNull($transmitter);
-    }
-
     public function testSendStatusCodeWithReasonPhrase()
     {
         $transmitter = new Transmitter();