Massive clean up of documentation

src/HandlerContainer.php

@@ -1,7 +1,10 @@
 <?php
-
+/** Handler Container - A container representing a route target (i.e. Controller) and a list of middleware for that route
+ *
+ */
 namespace Circuit;
 
+use Circuit\Router;
 use Circuit\Interfaces\Middleware;
 use Circuit\Interfaces\Delegate;
 use Circuit\Interfaces\ParameterDereferencer;
@@ -10,23 +13,25 @@
 
 class HandlerContainer implements Delegate
 {
-    /** @var Middleware|null[] Stack of middleware to call for this route */
+    /** @var Middleware|string|null[]  Stack of middleware to call for this route */
     public $middlewareStack = [null];
 
-    /** @var string The Controller class for this route */
+    /** @var string  The Controller class for this route */
     public $controllerClass;
 
-    /** @var string The method to call on the Controller for this route*/
+    /** @var string  The method to call on the Controller for this route */
     public $controllerMethod;
 
-    /** @var \Circuit\Router The router responsible for this route - this gets assigned when a route is executed */
+    /** @var Router  The router responsible for this route - this gets assigned when a route is executed */
     protected $router;
 
     /**
      * Store a handler against a list of middleware
      *
-     * @param mixed $handler
-     * @param Middleware[] $stack
+     * @param mixed               $handler  Name of the controller that will be called for this route. Must be supplied
+     *                                      Laravel style - "ControllerClass@MethodName"
+     * @param Middleware|string[] $stack    A list of middleware (Middleware Objects or named Middleware) to be called
+     *                                      before the controller
      */
     public function __construct($handler, array $stack = [])
     {
@@ -41,7 +46,7 @@ public function __construct($handler, array $stack = [])
     /**
      * Add middleware to an existing handler stack
      *
-     * @param Middleware[] $stack
+     * @param Middleware|string[] $stack Middleware to add to this route.
      * @return self
      */
     public function addMiddleware(array $stack)
@@ -54,9 +59,9 @@ public function addMiddleware(array $stack)
      * Start processing this route, by calling middleware in order, and then calling the specified Controller
      * This call stores various information (args, controller info) on the Request
      *
-     * @param Router $router The router calling this handler
+     * @param Router $router   The router calling this handler
      * @param Request $request The request for the current route
-     * @param array $args The matched arguments from the route
+     * @param array $args      The matched arguments from the route
      * @return Response
      */
     public function startProcessing(Router $router, Request $request, $args) : Response
@@ -65,7 +70,7 @@ public function startProcessing(Router $router, Request $request, $args) : Respo
         $request->attributes->set('args', $args);
         $request->attributes->set('class', $this->controllerClass);
         $request->attributes->set('method', $this->controllerMethod);
-        $request->attributes->set('constructor', $this->router->controllerArguments);
+        $request->attributes->set('constructor', $this->router->getControllerArguments());
         return $this->process($request);
     }
 

src/RouteCollector.php

@@ -10,22 +10,25 @@
 
 class RouteCollector
 {
-    /** @var RouteParser */
+    /** @var RouteParser FastRoute compatible Route Parser as set in Router::$options */
     protected $routeParser;
 
-    /** @var DataGenerator */
+    /** @var DataGenerator FastRoute compatible Data Generator as set in Router::$options */
     protected $dataGenerator;
 
-    /** @var string */
+    /** @var string Route prefix for current group(s) */
     protected $currentGroupPrefix;
+
+    /** @var Middleware|string[] Stack of middleware to append to defined routes. Will be temporarily added to during
+                                 ->addGroup() calls */
     protected $middlewareStack = [];
 
     /**
      * Constructs a route collector.
      *
-     * @param RouteParser   $routeParser
-     * @param DataGenerator $dataGenerator
-     * @param Middleware[]  $middleware
+     * @param RouteParser          $routeParser    FastRoute compatible Route Parser as set in Router::$options
+     * @param DataGenerator        $dataGenerator  FastRoute compatible Data Generator as set in Router::$options
+     * @param Middleware|string[]  $middleware     Array of middle ware to apply to all routes
      */
     public function __construct(RouteParser $routeParser, DataGenerator $dataGenerator, array $middleware = [])
     {
@@ -40,10 +43,12 @@ public function __construct(RouteParser $routeParser, DataGenerator $dataGenerat
      *
      * The syntax used in the $route string depends on the used route parser.
      *
-     * @param string|string[] $httpMethod
-     * @param string $route
-     * @param mixed  $handler
-     * @param Middleware[] $middleware
+     * @param string|string[] $httpMethod      HTTP Verb(s) for this route
+     * @param string $route                    The route
+     * @param mixed  $handler                  Either a handler specified Laravel style: "ControllerClass@MethodName"
+     *                                         or a pregenerated HandlerContainer object
+     * @param Middleware|string[] $middleware  List of middleware (Middleware objects or named middleware) to add to
+     *                                         this route
      */
     public function addRoute($httpMethod, $route, $handler, array $middleware = [])
     {
@@ -69,9 +74,9 @@ public function addRoute($httpMethod, $route, $handler, array $middleware = [])
      *
      * All routes created in the passed callback will have the given group prefix prepended.
      *
-     * @param string $prefix
-     * @param Middleware[] $middleware
-     * @param callable $callback
+     * @param string              $prefix      String to be prepended to this route
+     * @param Middleware|string[] $middleware  Middleware to be added to all routes in this group
+     * @param callable            $callback    Definition callback
      */
     public function addGroup($prefix, array $middleware, callable $callback)
     {
@@ -89,9 +94,11 @@ public function addGroup($prefix, array $middleware, callable $callback)
      *
      * This is simply an alias of $this->addRoute('GET', $route, $handler, $middleware)
      *
-     * @param string $route
-     * @param mixed  $handler
-     * @param Middleware[] $middleware
+     * @param string              $route       Defined route
+     * @param mixed               $handler     Either a handler specified Laravel style: "ControllerClass@MethodName"
+     *                                         or a pregenerated HandlerContainer object
+     * @param Middleware|string[] $middleware  List of middleware (Middleware objects or named middleware) to add to
+     *                                         this route
      */
     public function get($route, $handler, array $middleware = [])
     {
@@ -103,9 +110,11 @@ public function get($route, $handler, array $middleware = [])
      *
      * This is simply an alias of $this->addRoute('POST', $route, $handler, $middleware)
      *
-     * @param string $route
-     * @param mixed  $handler
-     * @param Middleware[] $middleware
+     * @param string              $route       Defined route
+     * @param mixed               $handler     Either a handler specified Laravel style: "ControllerClass@MethodName"
+     *                                         or a pregenerated HandlerContainer object
+     * @param Middleware|string[] $middleware  List of middleware (Middleware objects or named middleware) to add to
+     *                                         this route
      */
     public function post($route, $handler, array $middleware = [])
     {
@@ -117,9 +126,11 @@ public function post($route, $handler, array $middleware = [])
      *
      * This is simply an alias of $this->addRoute('PUT', $route, $handler, $middleware)
      *
-     * @param string $route
-     * @param mixed  $handler
-     * @param Middleware[] $middleware
+     * @param string              $route       Defined route
+     * @param mixed               $handler     Either a handler specified Laravel style: "ControllerClass@MethodName"
+     *                                         or a pregenerated HandlerContainer object
+     * @param Middleware|string[] $middleware  List of middleware (Middleware objects or named middleware) to add to
+     *                                         this route
      */
     public function put($route, $handler, array $middleware = [])
     {
@@ -131,9 +142,11 @@ public function put($route, $handler, array $middleware = [])
      *
      * This is simply an alias of $this->addRoute('DELETE', $route, $handler, $middleware)
      *
-     * @param string $route
-     * @param mixed  $handler
-     * @param Middleware[] $middleware
+     * @param string              $route       Defined route
+     * @param mixed               $handler     Either a handler specified Laravel style: "ControllerClass@MethodName"
+     *                                         or a pregenerated HandlerContainer object
+     * @param Middleware|string[] $middleware  List of middleware (Middleware objects or named middleware) to add to
+     *                                         this route
      */
     public function delete($route, $handler, array $middleware = [])
     {
@@ -145,27 +158,33 @@ public function delete($route, $handler, array $middleware = [])
      *
      * This is simply an alias of $this->addRoute('PATCH', $route, $handler, $middleware)
      *
-     * @param string $route
-     * @param mixed  $handler
-     * @param Middleware[] $middleware
+     * @param string              $route       Defined route
+     * @param mixed               $handler     Either a handler specified Laravel style: "ControllerClass@MethodName"
+     *                                         or a pregenerated HandlerContainer object
+     * @param Middleware|string[] $middleware  List of middleware (Middleware objects or named middleware) to add to
+     *                                         this route
      */
     public function patch($route, $handler, array $middleware = [])
     {
         $this->addRoute('PATCH', $route, $handler, $middleware);
     }
+
     /**
      * Adds a HEAD route to the collection
      *
      * This is simply an alias of $this->addRoute('HEAD', $route, $handler, $middleware)
      *
-     * @param string $route
-     * @param mixed  $handler
-     * @param Middleware[] $middleware
+     * @param string              $route       Defined route
+     * @param mixed               $handler     Either a handler specified Laravel style: "ControllerClass@MethodName"
+     *                                         or a pregenerated HandlerContainer object
+     * @param Middleware|string[] $middleware  List of middleware (Middleware objects or named middleware) to add to
+     *                                         this route
      */
     public function head($route, $handler, array $middleware = [])
     {
         $this->addRoute('HEAD', $route, $handler, $middleware);
     }
+
     /**
      * Returns the collected route data, as provided by the data generator.
      *