Legibility improvements on the Callback route

Author: alganet

library/Respect/Rest/Request.php

@@ -20,7 +20,11 @@ class Request
     /** @var string The HTTP method (commonly GET, POST, PUT, DELETE, HEAD) */
     public $method = '';
 
-    /** @var array A numeric array containing valid URL parameters */
+    /** 
+     * @var array A numeric array containing valid URL parameters. For a route
+     * path like /users/*, a Request for /users/alganet should have an array
+     * equivalent to ['alganet']
+     */
     public $params = array();
 
     /** @var AbstractRoute A route matched for this request */

library/Respect/Rest/Router.php

@@ -111,6 +111,8 @@ public static function compareRoutePatterns($patternA, $patternB, $sub)
      *
      * @param array $params an array of params
      *
+     * @see Respect\Rest\Request::$params
+     *
      * @return array only the non-empty params
      */
     protected static function cleanUpParams(array $params)
@@ -235,6 +237,8 @@ public function __toString()
      * @param array  $etc         This function accepts infinite params
      *                            that will be passed to the routine instance
      *
+     * @see Respect\Rest\Request::$params
+     *
      * @return Router the router itself.
      */
     public function always($routineName, $param1=null, $param2=null, $etc=null)
@@ -589,6 +593,8 @@ protected function applyVirtualHost()
      * @param AbstractRoute $route   Some route
      * @param array         $param   A list of URI params
      *
+     * @see Respect\Rest\Request::$params
+     *
      * @return Request a configured Request instance
      */
     protected function configureRequest(
@@ -678,6 +684,8 @@ protected function matchesMethod(AbstractRoute $route, $methodName)
      * @param AbstractRoute $route   Some route
      * @param array         $params  A list of URI params
      *
+     * @see Respect\Rest\Request::$params
+     *
      * @return bool true if the route matches the request with that params
      */
     protected function matchRoute(

library/Respect/Rest/Routes/AbstractRoute.php

@@ -56,16 +56,26 @@ abstract class AbstractRoute
 
     /** @var string The HTTP method for this route (GET, POST, ANY, etc) */
     public $method = '';
-    /** @var string The minimalistic pattern for route paths for this route */
+    /** @var string The pattern for this route (like /users/*) */
     public $pattern = '';
-    /** @var string The generated regex for the route pattern */
+    /** @var string The generated regex to match the route pattern */
     public $regexForMatch = '';
-    /** @var string The generated regex for creating URIs from parameters */
+    /** 
+     * @var string The generated regex for creating URIs from parameters 
+     * @see Respect\Rest\AbstractRoute::createURI
+     */
     public $regexForReplace = '';
-    /** @var array A list of routines appended to this route */
+    /** 
+     * @var array A list of routines appended to this route 
+     * @see Respect\Rest\Routines\AbstractRoutine
+     */
     public $routines = array();
-    /** @var array A list of side routes to be used */
+    /**
+     * @var array A list of side routes to be used
+     * @see Respect\Rest\Routes\AbstractRoute
+     */
     public $sideRoutes = array();
+    
     /** @var array A virtualhost applied to this route (deprecated) */
     public $virtualHost = null;
 
@@ -140,6 +150,8 @@ public function appendRoutine(Routinable $routine)
      * @param mixed $param1 Some parameter
      * @param mixed $etc    This route accepts as many parameters you can pass
      *
+     * @see Respect\Rest\Request::$params
+     *
      * @return string the created URI
      */
     public function createUri($param1=null, $etc=null)
@@ -158,6 +170,8 @@ public function createUri($param1=null, $etc=null)
      * @param array   $params  Parameters for the processed request
      * @see   Respect\Rest\Routines\ProxyableWhen
      *
+     * @see Respect\Rest\Request::$params
+     *
      * @return bool always true \,,/
      */
     public function matchRoutines(Request $request, $params=array())
@@ -184,6 +198,8 @@ public function matchRoutines(Request $request, $params=array())
      * @param Request $request The request you want to process
      * @param array   $params  Parameters for the processed request
      *
+     * @see Respect\Rest\Request::$params
+     *
      * @return bool as true as xkcd (always true)
      */
     public function match(Request $request, &$params=array())

library/Respect/Rest/Routes/Callback.php

@@ -9,20 +9,33 @@
 class Callback extends AbstractRoute
 {
 
+    /** @var callable The actual callback this route holds */
     protected $callback;
+    
+    /** @var array String argument parameters from the Request */
     public $arguments;
 
-    /** @var ReflectionFunctionAbstract */
+    /** @var ReflectionFunctionAbstract The reflection for the callback */
     protected $reflection;
 
+    /**
+     * @param string   $method    The HTTP method (GET, POST, etc)
+     * @param string   $pattern   The URI pattern for this route
+     * @param callable $callback  The callback this route holds
+     * @param array    $arguments Additional arguments for this callback
+     */
     public function __construct($method, $pattern, $callback, array $arguments=array())
     {
         $this->callback = $callback;
         $this->arguments = $arguments;
         parent::__construct($method, $pattern);
     }
 
-    /** Returns an appropriate Reflection for any is_callable object */
+    /** 
+     * Returns an appropriate Reflection for any callable object 
+     *
+     * @return ReflectionFunctionAbstract The returned reflection object
+     */
     public function getCallbackReflection()
     {
         if (is_array($this->callback))
@@ -31,6 +44,14 @@ public function getCallbackReflection()
             return new ReflectionFunction($this->callback);
     }
 
+    /**
+     * Gets the reflection for a specific method. For callables, the reflection
+     * is always the same. This follows the AbstractRoute implementation
+     *
+     * @param string $method The irrelevant HTTP method for this implementation
+     *
+     * @return ReflectionFunctionAbstract The returned reflection object
+     */
     public function getReflection($method)
     {
         if (empty($this->reflection))
@@ -39,9 +60,19 @@ public function getReflection($method)
         return $this->reflection;
     }
 
+    /**
+     * Runs the callback when this route is matched with params
+     *
+     * @param string $method The irrelevant HTTP method for this implementation
+     * @param array  $params An array of params for this request
+     *
+     * @see Respect\Rest\Request::$params
+     *
+     * @return mixed Whatever the callback returns
+     */
     public function runTarget($method, &$params)
     {
         return call_user_func_array($this->callback, array_merge($params, $this->arguments));
     }
 
-}
+}