From 863adabe12a87f165b80404b91d3cc628ec7f3b7 Mon Sep 17 00:00:00 2001
From: john <psychic@cakephp.org>
Date: Thu, 30 Oct 2008 19:30:17 +0000
Subject: [PATCH] Updating Controller docblocks with @link and updating
 docblock content and grammar.

git-svn-id: https://svn.cakephp.org/repo/branches/1.2.x.x@7808 3807eeeb-6ff5-0310-8944-8be069107fe0
---
 cake/libs/controller/controller.php | 91 ++++++++++++++++++-----------
 1 file changed, 57 insertions(+), 34 deletions(-)

diff --git a/cake/libs/controller/controller.php b/cake/libs/controller/controller.php
index 4de0d89eb..30e18d5ba 100644
--- a/cake/libs/controller/controller.php
+++ b/cake/libs/controller/controller.php
@@ -29,13 +29,13 @@ App::import('Core', array('Component', 'View'));
 /**
  * Controller
  *
- * Application controller (controllers are where you put all the actual code)
- * Provides basic functionality, such as rendering views (aka displaying templates).
- * Automatically selects model name from on singularized object class name
- * and creates the model object if proper class exists.
+ * Application controller class for organization of business logic.
+ * Provides basic functionality, such as rendering views inside layouts,
+ * automatic model availability, redirection, callbacks, and more.
  *
  * @package       cake
  * @subpackage    cake.cake.libs.controller
+ * @link          http://book.cakephp.org/view/49/Controllers
  *
  */
 class Controller extends Object {
@@ -44,10 +44,11 @@ class Controller extends Object {
  *
  * @var string
  * @access public
+ * @link http://book.cakephp.org/view/52/name
  */
 	var $name = null;
 /**
- * Stores the current URL, based from the webroot.
+ * Stores the current URL, relative to the webroot of the application.
  *
  * @var string
  * @access public
@@ -61,7 +62,7 @@ class Controller extends Object {
  */
 	var $webroot = null;
 /**
- * The name of the controller action that was requested.
+ * The name of the currently requested controller action.
  *
  * @var string
  * @access public
@@ -74,16 +75,18 @@ class Controller extends Object {
  *
  * @var mixed A single name as a string or a list of names as an array.
  * @access protected
+ * @link http://book.cakephp.org/view/53/components-helpers-and-uses
  */
 	var $uses = false;
 /**
  * An array containing the names of helpers this controller uses. The array elements should
- * not contain the -Helper part of the classname.
+ * not contain the "Helper" part of the classname.
  *
  * Example: var $helpers = array('Html', 'Javascript', 'Time', 'Ajax');
  *
  * @var mixed A single name as a string or a list of names as an array.
  * @access protected
+ * @link http://book.cakephp.org/view/53/components-helpers-and-uses
  */
 	var $helpers = array('Html', 'Form');
 /**
@@ -92,6 +95,7 @@ class Controller extends Object {
  *
  * @var array
  * @access public
+ * @link http://book.cakephp.org/view/55/The-Parameters-Attribute-params
  */
 	var $params = array();
 /**
@@ -105,7 +109,7 @@ class Controller extends Object {
 /**
  * Holds pagination defaults for controller actions. The keys that can be included
  * in this array are: 'conditions', 'fields', 'order', 'limit', 'page', and 'recursive',
- * similar to the parameters of Model->findAll().
+ * similar to the keys in the second parameter of Model::find().
  *
  * Pagination defaults can also be supplied in a model-by-model basis by using
  * the name of the model as a key for a pagination array:
@@ -115,10 +119,9 @@ class Controller extends Object {
  * 		'Comment' => array(...)
  * 	);
  *
- * See the manual chapter on Pagination for more information.
- *
  * @var array
  * @access public
+ * @link http://book.cakephp.org/view/164/Pagination
  */
 	var $paginate = array('limit' => 20, 'page' => 1);
 /**
@@ -129,7 +132,7 @@ class Controller extends Object {
  */
 	var $viewPath = null;
 /**
- * Sub-path for layout files.
+ * The name of the layouts subfolder containing layouts for this controller.
  *
  * @var string
  * @access public
@@ -148,6 +151,7 @@ class Controller extends Object {
  *
  * @var boolean
  * @access public
+ * @link http://book.cakephp.org/view/54/Page-related-Attributes-layout-and-pageTitle
  */
 	var $pageTitle = false;
 /**
@@ -165,12 +169,13 @@ class Controller extends Object {
  */
 	var $base = null;
 /**
- * The name of the layout file to render views inside of. The name specified
+ * The name of the layout file to render the view inside of. The name specified
  * is the filename of the layout in /app/views/layouts without the .ctp
  * extension.
  *
  * @var string
  * @access public
+ * @link http://book.cakephp.org/view/54/Page-related-Attributes-layout-and-pageTitle
  */
 	var $layout = 'default';
 /**
@@ -189,7 +194,7 @@ class Controller extends Object {
  */
 	var $autoLayout = true;
 /**
- * Instance of Component use to handle callbacks
+ * Instance of Component used to handle callbacks.
  *
  * @var string
  * @access public
@@ -197,12 +202,13 @@ class Controller extends Object {
 	var $Component = null;
 /**
  * Array containing the names of components this controller uses. Component names
- * should not contain the -Component portion of the classname.
+ * should not contain the "Component" portion of the classname.
  *
  * Example: var $components = array('Session', 'RequestHandler', 'Acl');
  *
  * @var array
  * @access public
+ * @link http://book.cakephp.org/view/53/components-helpers-and-uses
  */
 	var $components = array();
 /**
@@ -222,7 +228,7 @@ class Controller extends Object {
 /**
  * The output of the requested action.  Contains either a variable
  * returned from the action, or the data of the rendered view;
- * You can use this var in Child controllers' afterFilter() to alter output.
+ * You can use this var in child controllers' afterFilter() callbacks to alter output.
  *
  * @var string
  * @access public
@@ -250,6 +256,7 @@ class Controller extends Object {
  *
  * @var mixed
  * @access public
+ * @link http://book.cakephp.org/view/346/Caching-in-the-Controller
  */
 	var $cacheAction = false;
 /**
@@ -273,6 +280,7 @@ class Controller extends Object {
  *
  * @var mixed
  * @access public
+ * @link http://book.cakephp.org/view/105/Scaffolding
  */
 	var $scaffold = false;
 /**
@@ -297,7 +305,7 @@ class Controller extends Object {
 		parent::__construct();
 	}
 /**
- * Merge components, helpers, and uses vars from AppController and PluginAppController
+ * Merge components, helpers, and uses vars from AppController and PluginAppController.
  *
  * @return void
  * @access protected
@@ -371,12 +379,13 @@ class Controller extends Object {
 	}
 /**
  * Loads Model classes based on the the uses property
- * see Controller::loadModel(); for more info
- * Loads Components and prepares them for initailization
+ * see Controller::loadModel(); for more info.
+ * Loads Components and prepares them for initialization.
  *
  * @return mixed true if models found and instance created, or cakeError if models not found.
  * @access public
  * @see Controller::loadModel()
+ * @link http://book.cakephp.org/view/429/constructClasses
  */
 	function constructClasses() {
 		$this->__mergeVars();
@@ -465,14 +474,14 @@ class Controller extends Object {
 	}
 /**
  * Redirects to given $url, after turning off $this->autoRender.
- * Please notice that the script execution is not stopped after the redirect.
+ * Script execution is halted after the redirect.
  *
- * @param mixed $url A string or array-based URL pointing to another location
- *                   within the app, or an absolute URL
+ * @param mixed $url A string or array-based URL pointing to another location within the app, or an absolute URL
  * @param integer $status Optional HTTP status code (eg: 404)
  * @param boolean $exit If true, exit() will be called after the redirect
  * @return mixed void if $exit = false. Terminates script if $exit = true
  * @access public
+ * @link http://book.cakephp.org/view/425/redirect
  */
 	function redirect($url, $status = null, $exit = true) {
 		$this->autoRender = false;
@@ -585,13 +594,14 @@ class Controller extends Object {
 		header($status);
 	}
 /**
- * Saves a variable to use inside a template.
+ * Saves a variable for use inside a view template.
  *
  * @param mixed $one A string or an array of data.
  * @param mixed $two Value in case $one is a string (which then works as the key).
  * 				Unused if $one is an associative array, otherwise serves as the values to $one's keys.
  * @return void
  * @access public
+ * @link http://book.cakephp.org/view/427/set
  */
 	function set($one, $two = null) {
 		$data = array();
@@ -637,10 +647,11 @@ class Controller extends Object {
 		return call_user_func_array(array(&$this, $action), $args);
 	}
 /**
- * Controller callback to tie into Auth component.
+ * Controller callback to tie into Auth component. Only called when AuthComponent::authorize is set to 'controller'.
  *
  * @return bool true if authorized, false otherwise
  * @access public
+ * @link http://book.cakephp.org/view/396/authorize
  */
 	function isAuthorized() {
 		trigger_error(sprintf(__('%s::isAuthorized() is not defined.', true), $this->name), E_USER_WARNING);
@@ -686,14 +697,14 @@ class Controller extends Object {
 		return $this->validationErrors = (count($errors) ? $errors : false);
 	}
 /**
- * Gets an instance of the view object & prepares it for rendering the output, then
- * asks the view to actually do the job.
+ * Instantiates the correct view class, hands it its data, and uses it to render the view output.
  *
  * @param string $action Action name to render
  * @param string $layout Layout to use
  * @param string $file File to use for rendering
  * @return string Full output string of view contents
  * @access public
+ * @link http://book.cakephp.org/view/428/render
  */
 	function render($action = null, $layout = null, $file = null) {
 		$this->beforeRender();
@@ -744,12 +755,13 @@ class Controller extends Object {
 		return $this->output;
 	}
 /**
- * Gets the referring URL of this request
+ * Returns the referring URL for this request.
  *
  * @param string $default Default URL to use if HTTP_REFERER cannot be read from headers
  * @param boolean $local If true, restrict referring URLs to local server
  * @return string Referring URL
  * @access public
+ * @link http://book.cakephp.org/view/430/referer
  */
 	function referer($default = null, $local = false) {
 		$ref = env('HTTP_REFERER');
@@ -772,10 +784,11 @@ class Controller extends Object {
 		return '/';
 	}
 /**
- * Tells the browser not to cache the results of the current request by sending headers
+ * Forces the user's browser not to cache the results of the current request.
  *
  * @return void
  * @access public
+ * @link http://book.cakephp.org/view/431/disableCache
  */
 	function disableCache() {
 		header("Expires: Mon, 26 Jul 1997 05:00:00 GMT");
@@ -785,14 +798,16 @@ class Controller extends Object {
 		header("Pragma: no-cache");
 	}
 /**
- * Shows a message to the user $pause seconds, then redirects to $url
- * Uses flash.thtml as a layout for the messages
+ * Shows a message to the user for $pause seconds, then redirects to $url.
+ * Uses flash.ctp as the default layout for the message.
+ * Does not work if the current debug level is higher than 0.
  *
  * @param string $message Message to display to the user
  * @param string $url Relative URL to redirect to after the time expires
  * @param integer $pause Time to show the message
  * @return void Renders flash layout
  * @access public
+ * @link http://book.cakephp.org/view/426/flash
  */
 	function flash($message, $url, $pause = 1) {
 		$this->autoRender = false;
@@ -803,8 +818,7 @@ class Controller extends Object {
 		$this->render(false, 'flash');
 	}
 /**
- * Converts POST'ed model data to a model conditions array, suitable for a find
- * or findAll Model query
+ * Converts POST'ed form data to a model conditions array, suitable for use in a Model::find() call.
  *
  * @param array $data POST'ed data organized by model and field
  * @param mixed $op A string containing an SQL comparison operator, or an array matching operators to fields
@@ -812,6 +826,7 @@ class Controller extends Object {
  * @param boolean $exclusive If true, and $op is an array, fields not included in $op will not be included in the returned conditions
  * @return array An array of model conditions
  * @access public
+ * @link http://book.cakephp.org/view/432/postConditions
  */
 	function postConditions($data = array(), $op = null, $bool = 'AND', $exclusive = false) {
 		if (!is_array($data) || empty($data)) {
@@ -864,6 +879,7 @@ class Controller extends Object {
  * @param array $whitelist List of allowed options for paging
  * @return array Model query results
  * @access public
+ * @link http://book.cakephp.org/view/165/Controller-Setup
  */
 	function paginate($object = null, $scope = array(), $whitelist = array()) {
 		if (is_array($object)) {
@@ -1034,23 +1050,26 @@ class Controller extends Object {
 		return $results;
 	}
 /**
- * Called before the controller action. Overridden in subclasses.
+ * Called before the controller action.
  *
  * @access public
+ * @link http://book.cakephp.org/view/60/Callbacks
  */
 	function beforeFilter() {
 	}
 /**
- * Called after the controller action is run, but before the view is rendered. Overridden in subclasses.
+ * Called after the controller action is run, but before the view is rendered.
  *
  * @access public
+ * @link http://book.cakephp.org/view/60/Callbacks
  */
 	function beforeRender() {
 	}
 /**
- * Called after the controller action is run and rendered. Overridden in subclasses.
+ * Called after the controller action is run and rendered.
  *
  * @access public
+ * @link http://book.cakephp.org/view/60/Callbacks
  */
 	function afterFilter() {
 	}
@@ -1060,6 +1079,7 @@ class Controller extends Object {
  * @param string $method name of method called example index, edit, etc.
  * @return boolean Success
  * @access protected
+ * @link http://book.cakephp.org/view/60/Callbacks
  */
 	function _beforeScaffold($method) {
 		return true;
@@ -1070,6 +1090,7 @@ class Controller extends Object {
  * @param string $method name of method called either edit or update.
  * @return boolean Success
  * @access protected
+ * @link http://book.cakephp.org/view/60/Callbacks
  */
 	function _afterScaffoldSave($method) {
 		return true;
@@ -1080,6 +1101,7 @@ class Controller extends Object {
  * @param string $method name of method called either edit or update.
  * @return boolean Success
  * @access protected
+ * @link http://book.cakephp.org/view/60/Callbacks
  */
 	function _afterScaffoldSaveError($method) {
 		return true;
@@ -1092,6 +1114,7 @@ class Controller extends Object {
  * @param string $method name of method called example index, edit, etc.
  * @return boolean Success
  * @access protected
+ * @link http://book.cakephp.org/view/60/Callbacks
  */
 	function _scaffoldError($method) {
 		return false;