Expand docs on router cases; fix types documented.

net/http/Route.php

@@ -147,7 +147,21 @@ class Route extends \lithium\core\Object {
 	 * `Response` object, in which case the response will be returned directly. This may be used to
 	 * handle redirects, or simple API services.
 	 *
-	 * @var object
+	 * ```
+	 * new Route(array(
+	 *     'template' => '/photos/{:id:[0-9]+}.jpg',
+	 *     'handler' => function($request) {
+	 *         return new Response(array(
+	 *             'headers' => array('Content-type' => 'image/jpeg'),
+	 *             'body' => Photos::first($request->id)->bytes()
+	 *         ));
+	 *     }
+	 * });
+	 * ```
+	 *
+	 * @see lithium\net\http\Route::parse()
+	 * @see lithium\net\http\Response
+	 * @var callable
 	 */
 	protected $_handler = null;
 
@@ -207,14 +221,19 @@ protected function _init() {
 	/**
 	 * Attempts to parse a request object and determine its execution details.
 	 *
+	 * @see lithium\net\http\Request
+	 * @see lithium\net\http\Request::$params
+	 * @see lithium\net\http\Route::$_handler
 	 * @param object $request A request object, usually an instance of `lithium\net\http\Request`,
-	 *        containing the details of the request to be routed.
+	 *               containing the details of the request to be routed.
 	 * @param array $options Used to determine the operation of the method, and override certain
 	 *              values in the `Request` object:
 	 *              - `'url'` _string_: If present, will be used to match in place of the `$url`
 	 *                 property of `$request`.
-	 * @return mixed If this route matches `$request`, returns an array of the execution details
-	 *         contained in the route, otherwise returns false.
+	 * @return object|boolean If this route matches `$request`, returns the request with
+	 *         execution details attached to it (inside `Request::$params`). Alternatively when
+	 *         a route handler function was used, returns the result of its invocation. Returns
+	 *         `false` if the route never matched.
 	 */
 	public function parse($request, array $options = array()) {
 		$defaults = array('url' => $request->url);

net/http/Router.php

@@ -128,12 +128,32 @@ public static function config($config = array()) {
 	 * matters, since the order of precedence is taken into account in parsing and matching
 	 * operations.
 	 *
+	 * A callable can be passed in place of `$options`. In this case the callable acts as a *route
+	 * handler*. Route handlers should return an instance of `lithium\net\http\Response`
+	 * and can be used to short-circuit the framework's lookup and invocation of controller
+	 * actions:
+	 * ```
+	 * Router::connect('/photos/{:id:[0-9]+}.jpg', array(), function($request) {
+	 *     return new Response(array(
+	 *         'headers' => array('Content-type' => 'image/jpeg'),
+	 *         'body' => Photos::first($request->id)->bytes()
+	 *     ));
+	 * });
+	 * ```
+	 *
 	 * @see lithium\net\http\Route
+	 * @see lithium\net\http\Route::$_handler
 	 * @see lithium\net\http\Router::parse()
 	 * @see lithium\net\http\Router::match()
-	 * @param string $template An empty string, or a route string "/"
-	 * @param array $params An array describing the default or required elements of the route
-	 * @param array $options
+	 * @see lithium\net\http\Router::_parseString()
+	 * @see lithium\net\http\Response
+	 * @param string|object $template An empty string, a route string `/` or an
+	 *                      instance of `lithium\net\http\Route`.
+	 * @param array|string $params An array describing the default or required elements of
+	 *                     the route or alternatively a path string i.e. `Posts::index`.
+	 * @param array|callable $options Either an array of options (`'handler'`, `'formatters'`,
+	 *                      `'modifiers'`, `'unicode'` as well as any options for `Route`) or
+	 *                      a callable that will be used as a route handler.
 	 * @return array Array of routes
 	 */
 	public static function connect($template, $params = array(), $options = array()) {
@@ -615,7 +635,7 @@ public static function reset() {
 	/**
 	 * Helper function for taking a path string and parsing it into a controller and action array.
 	 *
-	 * @param string $path Path string to parse.
+	 * @param string $path Path string to parse i.e. `li3_bot.Logs::index` or `Posts::index`.
 	 * @param boolean $context
 	 * @return array
 	 */