From d9fbe5e00a88802c35bf8509cc8421b3ed2c80df Mon Sep 17 00:00:00 2001 From: mark_story Date: Tue, 26 Feb 2013 21:43:53 -0500 Subject: [PATCH] Tidy up doc blocks. These kind of changes make tidyier method summaries in apigen. --- lib/Cake/Controller/Component.php | 2 +- .../Controller/Component/AuthComponent.php | 24 ++++++++++++------ lib/Cake/Controller/Controller.php | 4 ++- lib/Cake/Routing/Route/CakeRoute.php | 25 +++++++++++++------ lib/Cake/Routing/Router.php | 22 ++++++++++------ 5 files changed, 53 insertions(+), 24 deletions(-) diff --git a/lib/Cake/Controller/Component.php b/lib/Cake/Controller/Component.php index dd999dc1f..74f735fa3 100644 --- a/lib/Cake/Controller/Component.php +++ b/lib/Cake/Controller/Component.php @@ -158,7 +158,7 @@ class Component extends Object { * @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) { } diff --git a/lib/Cake/Controller/Component/AuthComponent.php b/lib/Cake/Controller/Component/AuthComponent.php index 123483925..8f68c9b7c 100644 --- a/lib/Cake/Controller/Component/AuthComponent.php +++ b/lib/Cake/Controller/Component/AuthComponent.php @@ -385,6 +385,8 @@ class AuthComponent extends Component { } /** + * 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 @@ class AuthComponent extends Component { } /** - * 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 @@ class AuthComponent extends Component { } /** - * 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 @@ class AuthComponent extends Component { } /** - * 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 @@ class AuthComponent extends Component { } /** + * 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. diff --git a/lib/Cake/Controller/Controller.php b/lib/Cake/Controller/Controller.php index f78e0cd30..0e4ba7384 100644 --- a/lib/Cake/Controller/Controller.php +++ b/lib/Cake/Controller/Controller.php @@ -1096,7 +1096,9 @@ class Controller extends Object implements CakeEventListener { /** * 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'. diff --git a/lib/Cake/Routing/Route/CakeRoute.php b/lib/Cake/Routing/Route/CakeRoute.php index 083de8575..83a2ad55c 100644 --- a/lib/Cake/Routing/Route/CakeRoute.php +++ b/lib/Cake/Routing/Route/CakeRoute.php @@ -103,7 +103,9 @@ class CakeRoute { } /** - * 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 @@ class CakeRoute { } /** - * 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 @@ class CakeRoute { /** * 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 @@ class CakeRoute { } /** - * 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 @@ class CakeRoute { } /** - * 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 @@ class CakeRoute { } /** - * 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. diff --git a/lib/Cake/Routing/Router.php b/lib/Cake/Routing/Router.php index da587d1c1..48d694fd6 100644 --- a/lib/Cake/Routing/Router.php +++ b/lib/Cake/Routing/Router.php @@ -1008,9 +1008,11 @@ class Router { } /** - * 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 @@ class Router { } /** - * 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 @@ class Router { } /** - * 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 @@ class Router { /** * 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 @@ class Router { /** * 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