Revise docblocks for interfaces.

src/Dispatching/DispatchStackInterface.php

@@ -7,14 +7,14 @@ use Psr\Http\Message\ServerRequestInterface;
 use WellRESTed\MiddlewareInterface;
 
 /**
- * Dispatches an ordered sequence of middleware.
+ * Dispatches an ordered sequence of middleware
  */
 interface DispatchStackInterface extends MiddlewareInterface
 {
     /**
      * Push a new middleware onto the stack.
      *
-     * This method MUST preserve the order in which middleware added.
+     * This method MUST preserve the order in which middleware are added.
      *
      * @param mixed $middleware Middleware to dispatch in sequence
      * @return self
@@ -31,9 +31,9 @@ interface DispatchStackInterface extends MiddlewareInterface
      * middleware. The last middleware MUST receive a $next callable that
      * returns the response unchanged.
      *
-     * When any middleware does not call the $next argument it recieved, the
+     * When any middleware returns a response without calling the $next
-     * stack instance MUST stop propogating through the stack and MUST return
+     * argument it recieved, the stack instance MUST stop propogating and MUST
-     * the response without calling the $next argument passed to dispatch.
+     * return a response without calling the $next argument passed to __invoke.
      *
      * This method MUST call the passed $next argument when:
      * - The stack is empty (i.e., there is no middleware to dispatch)

src/Dispatching/DispatcherInterface.php

@@ -5,6 +5,9 @@ namespace WellRESTed\Dispatching;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
 
+/**
+ * Dispatches middleware
+ */
 interface DispatcherInterface
 {
     /**
@@ -22,11 +25,11 @@ interface DispatcherInterface
      * - 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::dispatch
+     * - A callable with a signature matching MiddlewareInterface::__invoke
      *
      * Implementation MAY dispatch other types of middleware.
      *
-     * When an implementation recieves a $middware that is not of a type it can
+     * When an implementation receives a $middware that is not of a type it can
      * dispatch, it MUST throw a DispatchException.
      *
      * @param mixed $middleware

src/MiddlewareInterface.php

@@ -8,6 +8,27 @@ use Psr\Http\Message\ServerRequestInterface;
 interface MiddlewareInterface
 {
     /**
+     * Accepts a request and response and returns a modified response.
+     *
+     * $request represents the request issued by the client.
+     *
+     * $response represents the current state of the response.
+     *
+     * $next is a callable that expects a request and response as parameters
+     * and returns a response. Calling $next forwards a request and response
+     * to the next middleware in the sequence (if any) and continues
+     * propagation; returning a response without calling $next halts propgation
+     * and prevents subsequent middleware from running.
+     *
+     * Implementations MAY call $next to continue propagation. After calling
+     * $next, implementations MUST return the response returned by $next or
+     * use $next's returned response to determine the response it will
+     * ulitimately return. Implementations MUST NOT call $next and disregard
+     * $next's returned response.
+     *
+     * Implementaitons MAY return a response without calling $next to halt
+     * propagation.
+     *
      * @param ServerRequestInterface $request
      * @param ResponseInterface $response
      * @param callable $next

src/Routing/MethodMapInterface.php

@@ -2,10 +2,28 @@
 
 namespace WellRESTed\Routing;
 
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
 use WellRESTed\MiddlewareInterface;
 
+/**
+ * Maps HTTP methods to middleware
+ */
 interface MethodMapInterface extends MiddlewareInterface
 {
+    /**
+     * Evaluate $request's method and dispatches matching middleware.
+     *
+     * Implementations MUST pass $request, $response, and $next to the matching
+     * middleware.
+     *
+     * @param ServerRequestInterface $request
+     * @param ResponseInterface $response
+     * @param callable $next
+     * @return ResponseInterface
+     */
+    public function __invoke(ServerRequestInterface $request, ResponseInterface $response, $next);
+
     /**
      * Register middleware with a method.
      *
@@ -22,9 +40,6 @@ interface MethodMapInterface extends MiddlewareInterface
      * - A callable maching the signature of MiddlewareInteraface::dispatch
      * @see DispatcherInterface::dispatch
      *
-     * $middleware may also be null, in which case any previously set
-     * middleware for that method or methods will be unset.
-     *
      * @param string $method
      * @param mixed $middleware
      */

src/Routing/Route/RouteFactoryInterface.php

@@ -7,9 +7,9 @@ interface RouteFactoryInterface
     /**
      * Creates a route for the given target.
      *
-     * - Target with no special characters will create StaticRoutes
+     * - Targets with no special characters will create StaticRoutes
-     * - Target ending with * will create PrefixRoutes
+     * - Targets ending with * will create PrefixRoutes
-     * - Target containing URI variables (e.g., {id}) will create TemplateRoutes
+     * - Targets containing URI variables (e.g., {id}) will create TemplateRoutes
      * - Regular exressions will create RegexRoutes
      *
      * @param string $target Route target or target pattern

src/Routing/Route/RouteInterface.php

@@ -39,7 +39,7 @@ interface RouteInterface extends MiddlewareInterface
 
     /**
      * Return an array of variables extracted from the path most recently
-     * passed to  matchesRequestTarget.
+     * passed to matchesRequestTarget.
      *
      * If the path does not contain variables, or if matchesRequestTarget
      * has not yet been called, this method MUST return an empty array.

src/Routing/Router.php

@@ -4,7 +4,6 @@ namespace WellRESTed\Routing;
 
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
-use WellRESTed\Dispatching\Dispatcher;
 use WellRESTed\Dispatching\DispatcherInterface;
 use WellRESTed\Routing\Route\RouteFactory;
 use WellRESTed\Routing\Route\RouteFactoryInterface;

src/Routing/RouterInterface.php

@@ -2,23 +2,41 @@
 
 namespace WellRESTed\Routing;
 
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
 use WellRESTed\MiddlewareInterface;
 
+/**
+ * Maps HTTP methods and paths to middleware
+ */
 interface RouterInterface extends MiddlewareInterface
 {
+    /**
+     * Evaluate $request's path and method and dispatches matching middleware.
+     *
+     * Implementations MUST pass $request, $response, and $next to the matching
+     * middleware.
+     *
+     * @param ServerRequestInterface $request
+     * @param ResponseInterface $response
+     * @param callable $next
+     * @return ResponseInterface
+     */
+    public function __invoke(ServerRequestInterface $request, ResponseInterface $response, $next);
+
     /**
      * Register middleware with the router for a given path and method.
      *
      * $method may be:
-     * - A single verb ("GET"),
+     * - A single verb ("GET")
      * - A comma-separated list of verbs ("GET,PUT,DELETE")
-     * - "*" to indicate any method.
+     * - "*" to indicate any method
      * @see MethodMapInterface::register
      *
      * $target may be:
      * - An exact path (e.g., "/path/")
-     * - An prefix path ending with "*"" ("/path/*"")
+     * - A prefix path ending with "*"" ("/path/*"")
-     * - A URI template with variables enclosed in "{}" ("/path/{id}")
+     * - A URI template with one or more variables ("/path/{id}")
      * - A regular expression ("~/cat/([0-9]+)~")
      *
      * $middleware may be: