Tidy up doc blocks.

These kind of changes make tidyier method summaries in apigen.

lib/Cake/Controller/Component.php

@@ -158,7 +158,7 @@ public function shutdown(Controller $controller) {
  * @param integer $status The status code of the redirect
  * @param boolean $exit Will the script exit.
  * @return array|void Either an array or null.
- * @link @link http://book.cakephp.org/2.0/en/controllers/components.html#Component::beforeRedirect
+ * @link http://book.cakephp.org/2.0/en/controllers/components.html#Component::beforeRedirect
  */
 	public function beforeRedirect(Controller $controller, $url, $status = null, $exit = true) {
 	}

lib/Cake/Controller/Component/AuthComponent.php

@@ -385,6 +385,8 @@ protected function _setDefaults() {
 	}
 
 /**
+ * Check if the provided user is authorized for the request.
+ *
  * Uses the configured Authorization adapters to check whether or not a user is authorized.
  * Each adapter will be checked in sequence, if any of them return true, then the user will
  * be authorized for the request.
@@ -506,7 +508,9 @@ public function deny($action = null) {
 	}
 
 /**
- * Maps action names to CRUD operations. Used for controller-based authentication. Make sure
+ * Maps action names to CRUD operations.
+ *
+ * Used for controller-based authentication. Make sure
  * to configure the authorize property before calling this method. As it delegates $map to all the
  * attached authorize objects.
  *
@@ -525,7 +529,9 @@ public function mapActions($map = array()) {
 	}
 
 /**
- * Log a user in. If a $user is provided that data will be stored as the logged in user. If `$user` is empty or not
+ * Log a user in.
+ *
+ * If a $user is provided that data will be stored as the logged in user. If `$user` is empty or not
  * specified, the request will be used to identify a user. If the identification was successful,
  * the user record is written to the session key specified in AuthComponent::$sessionKey. Logging in
  * will also change the session id in order to help mitigate session replays.
@@ -548,11 +554,13 @@ public function login($user = null) {
 	}
 
 /**
- * Logs a user out, and returns the login action to redirect to.
- * Triggers the logout() method of all the authenticate objects, so they can perform
- * custom logout logic. AuthComponent will remove the session data, so
- * there is no need to do that in an authentication object. Logging out
- * will also renew the session id. This helps mitigate issues with session replays.
+ * Log a user out. 
+ *
+ * Returns the login action to redirect to. Triggers the logout() method of
+ * all the authenticate objects, so they can perform custom logout logic.
+ * AuthComponent will remove the session data, so there is no need to do that
+ * in an authentication object. Logging out will also renew the session id.
+ * This helps mitigate issues with session replays.
  *
  * @return string AuthComponent::$logoutRedirect
  * @see AuthComponent::$logoutRedirect
@@ -635,6 +643,8 @@ public function redirect($url = null) {
 	}
 
 /**
+ * Get the URL a use should be redirected to upon login.
+ *
  * If no parameter is passed, gets the authentication redirect URL. Pass a url in to
  * set the destination a user should be redirected to upon logging in. Will fallback to
  * AuthComponent::$loginRedirect if there is no stored redirect value.

lib/Cake/Controller/Controller.php

@@ -1096,7 +1096,9 @@ public function beforeRender() {
 
 /**
  * The beforeRedirect method is invoked when the controller's redirect method is called but before any
- * further action. If this method returns false the controller will not continue on to redirect the request.
+ * further action.
+ *
+ * If this method returns false the controller will not continue on to redirect the request.
  * The $url, $status and $exit variables have same meaning as for the controller's method. You can also
  * return a string which will be interpreted as the url to redirect to or return associative array with
  * key 'url' and optionally 'status' and 'exit'.

lib/Cake/Routing/Route/CakeRoute.php

@@ -103,7 +103,9 @@ public function compiled() {
 	}
 
 /**
- * Compiles the route's regular expression. Modifies defaults property so all necessary keys are set
+ * Compiles the route's regular expression.
+ *
+ * Modifies defaults property so all necessary keys are set
  * and populates $this->names with the named routing elements.
  *
  * @return array Returns a string regular expression of the compiled route.
@@ -117,8 +119,10 @@ public function compile() {
 	}
 
 /**
- * Builds a route regular expression. Uses the template, defaults and options
- * properties to compile a regular expression that can be used to parse request strings.
+ * Builds a route regular expression.
+ *
+ * Uses the template, defaults and options properties to compile a
+ * regular expression that can be used to parse request strings.
  *
  * @return void
  */
@@ -172,6 +176,7 @@ protected function _writeRoute() {
 
 /**
  * Checks to see if the given URL can be parsed by this route.
+ *
  * If the route can be parsed an array of parameters will be returned; if not
  * false will be returned. String urls are parsed if they match a routes regular expression.
  *
@@ -324,8 +329,10 @@ protected function _parseArgs($args, $context) {
 	}
 
 /**
- * Return true if a given named $param's $val matches a given $rule depending on $context. Currently implemented
- * rule types are controller, action and match that can be combined with each other.
+ * Check if a named parameter matches the current rules.
+ *
+ * Return true if a given named $param's $val matches a given $rule depending on $context.
+ * Currently implemented rule types are controller, action and match that can be combined with each other.
  *
  * @param string $val The value of the named parameter
  * @param array $rule The rule(s) to apply, can also be a match string
@@ -379,7 +386,9 @@ public function persistParams($url, $params) {
 	}
 
 /**
- * Attempt to match a url array. If the url matches the route parameters and settings, then
+ * Check if a url array matches this route instance.
+ *
+ * If the url matches the route parameters and settings, then
  * return a generated string url. If the url doesn't match the route parameters, false will be returned.
  * This method handles the reverse routing or conversion of url arrays into string urls.
  *
@@ -472,7 +481,9 @@ public function match($url) {
 	}
 
 /**
- * Converts a matching route array into a url string. Composes the string url using the template
+ * Converts a matching route array into a url string.
+ *
+ * Composes the string url using the template
  * used to create the route.
  *
  * @param array $params The params to convert to a string url.

lib/Cake/Routing/Router.php

@@ -1008,9 +1008,11 @@ public static function queryString($q, $extra = array(), $escape = false) {
 	}
 
 /**
- * Reverses a parsed parameter array into a string. Works similarly to Router::url(), but
- * Since parsed URL's contain additional 'pass' and 'named' as well as 'url.url' keys.
- * Those keys need to be specially handled in order to reverse a params array into a string url.
+ * Reverses a parsed parameter array into a string.
+ *
+ * Works similarly to Router::url(), but since parsed URL's contain additional
+ * 'pass' and 'named' as well as 'url.url' keys. Those keys need to be specially
+ * handled in order to reverse a params array into a string url.
  *
  * This will strip out 'autoRender', 'bare', 'requested', and 'return' param names as those
  * are used for CakePHP internals and should not normally be part of an output url.
@@ -1043,9 +1045,10 @@ public static function reverse($params, $full = false) {
 	}
 
 /**
- * Normalizes a URL for purposes of comparison. Will strip the base path off
- * and replace any double /'s. It will not unify the casing and underscoring
- * of the input value.
+ * Normalizes a URL for purposes of comparison.
+ *
+ * Will strip the base path off and replace any double /'s.
+ * It will not unify the casing and underscoring of the input value.
  *
  * @param array|string $url URL to normalize Either an array or a string url.
  * @return string Normalized URL
@@ -1115,8 +1118,9 @@ public static function stripPlugin($base, $plugin = null) {
 	}
 
 /**
- * Instructs the router to parse out file extensions from the URL. For example,
- * http://example.com/posts.rss would yield an file extension of "rss".
+ * Instructs the router to parse out file extensions from the URL.
+ *
+ * For example, http://example.com/posts.rss would yield an file extension of "rss".
  * The file extension itself is made available in the controller as
  * `$this->params['ext']`, and is used by the RequestHandler component to
  * automatically switch to alternate layouts and templates, and load helpers
@@ -1139,6 +1143,7 @@ public static function parseExtensions() {
 
 /**
  * Get the list of extensions that can be parsed by Router.
+ *
  * To initially set extensions use `Router::parseExtensions()`
  * To add more see `setExtensions()`
  *
@@ -1154,6 +1159,7 @@ public static function extensions() {
 
 /**
  * Set/add valid extensions.
+ *
  * To have the extensions parsed you still need to call `Router::parseExtensions()`
  *
  * @param array $extensions List of extensions to be added as valid extension