More API docblock fixes.

lib/Cake/Controller/CakeErrorController.php

@@ -39,8 +39,8 @@ class CakeErrorController extends AppController {
 /**
  * Constructor
  *
- * @param CakeRequest $request
- * @param CakeResponse $response
+ * @param CakeRequest $request Request instance.
+ * @param CakeResponse $response Response instance.
  */
 	public function __construct($request = null, $response = null) {
 		parent::__construct($request, $response);

lib/Cake/Controller/Component/AclComponent.php

@@ -53,8 +53,8 @@ class AclComponent extends Component {
 /**
  * Constructor. Will return an instance of the correct ACL class as defined in `Configure::read('Acl.classname')`
  *
- * @param ComponentCollection $collection
- * @param array $settings
+ * @param ComponentCollection $collection Collection instance.
+ * @param array $settings Settings list.
  * @throws CakeException when Acl.classname could not be loaded.
  */
 	public function __construct(ComponentCollection $collection, $settings = array()) {

lib/Cake/Controller/Component/Auth/AbstractPasswordHasher.php

@@ -1,7 +1,5 @@
 <?php
 /**
- *
- *
  * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
  * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
  *
@@ -66,7 +64,7 @@ abstract public function hash($password);
  * and check against existing hash.
  *
  * @param string|array $password Plain text password to hash or data array.
- * @param string Existing hashed password.
+ * @param string $hashedPassword Existing hashed password.
  * @return boolean True if hashes match else false.
  */
 	abstract public function check($password, $hashedPassword);

lib/Cake/Controller/Component/Auth/BaseAuthorize.php

@@ -1,7 +1,5 @@
 <?php
 /**
- *
- *
  * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
  * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
  *
@@ -79,7 +77,7 @@ public function __construct(ComponentCollection $collection, $settings = array()
  * Checks user authorization.
  *
  * @param array $user Active user data
- * @param CakeRequest $request
+ * @param CakeRequest $request Request instance.
  * @return boolean
  */
 	abstract public function authorize($user, CakeRequest $request);
@@ -107,7 +105,7 @@ public function controller(Controller $controller = null) {
  * that need to get information about the plugin, controller, and action being invoked.
  *
  * @param CakeRequest $request The request a path is needed for.
- * @param string $path
+ * @param string $path Path format.
  * @return string the action path for the given request.
  */
 	public function action(CakeRequest $request, $path = '/:plugin/:controller/:action') {
@@ -144,7 +142,7 @@ public function action(CakeRequest $request, $path = '/:plugin/:controller/:acti
  *
  * You can use the custom CRUD operations to create additional generic permissions
  * that behave like CRUD operations. Doing this will require additional columns on the
- * permissions lookup. For example if one wanted an additional search CRUD operation 
+ * permissions lookup. For example if one wanted an additional search CRUD operation
  * one would create and additional column '_search' in the aros_acos table. One could
  * create a custom admin CRUD operation for administration functions similarly if needed.
  *

lib/Cake/Controller/Component/Auth/BlowfishPasswordHasher.php

@@ -1,7 +1,5 @@
 <?php
 /**
- *
- *
  * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
  * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
  *
@@ -40,7 +38,7 @@ public function hash($password) {
  * Check hash. Generate hash for user provided password and check against existing hash.
  *
  * @param string $password Plain text password to hash.
- * @param string Existing hashed password.
+ * @param string $hashedPassword Existing hashed password.
  * @return boolean True if hashes match else false.
  */
 	public function check($password, $hashedPassword) {

lib/Cake/Controller/Component/Auth/ControllerAuthorize.php

@@ -1,7 +1,5 @@
 <?php
 /**
- *
- *
  * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
  * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
  *
@@ -58,7 +56,7 @@ public function controller(Controller $controller = null) {
  * Checks user authorization using a controller callback.
  *
  * @param array $user Active user data
- * @param CakeRequest $request
+ * @param CakeRequest $request Request instance.
  * @return boolean
  */
 	public function authorize($user, CakeRequest $request) {

lib/Cake/Controller/Component/Auth/SimplePasswordHasher.php

@@ -1,7 +1,5 @@
 <?php
 /**
- *
- *
  * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
  * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
  *
@@ -47,7 +45,7 @@ public function hash($password) {
  * Check hash. Generate hash for user provided password and check against existing hash.
  *
  * @param string $password Plain text password to hash.
- * @param string Existing hashed password.
+ * @param string $hashedPassword Existing hashed password.
  * @return boolean True if hashes match else false.
  */
 	public function check($password, $hashedPassword) {

lib/Cake/Controller/Component/AuthComponent.php

@@ -512,7 +512,7 @@ public function constructAuthorize() {
  * `$this->Auth->allow('edit', 'add');` or
  * `$this->Auth->allow();` to allow all actions
  *
- * @param string|array $action,... Controller action name or array of actions
+ * @param string|array $action Controller action name or array of actions
  * @return void
  * @link http://book.cakephp.org/2.0/en/core-libraries/components/authentication.html#making-actions-public
  */
@@ -537,7 +537,7 @@ public function allow($action = null) {
  * `$this->Auth->deny('edit', 'add');` or
  * `$this->Auth->deny();` to remove all items from the allowed list
  *
- * @param string|array $action,... Controller action name or array of actions
+ * @param string|array $action Controller action name or array of actions
  * @return void
  * @see AuthComponent::allow()
  * @link http://book.cakephp.org/2.0/en/core-libraries/components/authentication.html#making-actions-require-authorization

lib/Cake/Controller/Component/CookieComponent.php

@@ -185,7 +185,7 @@ public function __construct(ComponentCollection $collection, $settings = array()
 /**
  * Start CookieComponent for use in the controller
  *
- * @param Controller $controller
+ * @param Controller $controller Controller instance.
  * @return void
  */
 	public function startup(Controller $controller) {
@@ -293,7 +293,7 @@ public function read($key = null) {
 /**
  * Returns true if given variable is set in cookie.
  *
- * @param string $var Variable name to check for
+ * @param string $key Variable name to check for
  * @return boolean True if variable is there
  */
 	public function check($key = null) {

lib/Cake/Controller/Component/EmailComponent.php

@@ -423,7 +423,7 @@ protected function _findFiles($attachment) {
 /**
  * Format addresses to be an array with email as key and alias as value
  *
- * @param array $addresses
+ * @param array $addresses Address to format.
  * @return array
  */
 	protected function _formatAddresses($addresses) {

lib/Cake/Controller/Component/RequestHandlerComponent.php

@@ -224,7 +224,7 @@ public function startup(Controller $controller) {
  * Helper method to parse xml input data, due to lack of anonymous functions
  * this lives here.
  *
- * @param string $xml
+ * @param string $xml XML string.
  * @return array Xml array data
  */
 	public function convertXml($xml) {
@@ -246,7 +246,7 @@ public function convertXml($xml) {
  * @param Controller $controller A reference to the controller
  * @param string|array $url A string or array containing the redirect location
  * @param integer|array $status HTTP Status for redirect
- * @param boolean $exit
+ * @param boolean $exit Whether to exit script, defaults to `true`.
  * @return void
  */
 	public function beforeRedirect(Controller $controller, $url, $status = null, $exit = true) {
@@ -279,7 +279,7 @@ public function beforeRedirect(Controller $controller, $url, $status = null, $ex
  * render process is skipped. And the client will get a blank response with a
  * "304 Not Modified" header.
  *
- * @params Controller $controller
+ * @param Controller $controller Controller instance.
  * @return boolean false if the render process should be aborted
  */
 	public function beforeRender(Controller $controller) {
@@ -444,9 +444,10 @@ public function getReferer() {
 /**
  * Gets remote client IP
  *
- * @param boolean $safe
+ * @param boolean $safe Use safe = false when you think the user might manipulate
+ *   their HTTP_CLIENT_IP header. Setting $safe = false will also look at HTTP_X_FORWARDED_FOR
  * @return string Client IP address
- * @deprecated use $this->request->clientIp() from your,  controller instead.
+ * @deprecated use $this->request->clientIp() from your, controller instead.
  */
 	public function getClientIP($safe = true) {
 		return $this->request->clientIp($safe);

lib/Cake/Controller/Controller.php

@@ -346,7 +346,7 @@ public function __construct($request = null, $response = null) {
  * Provides backwards compatibility to avoid problems with empty and isset to alias properties.
  * Lazy loads models using the loadModel() method if declared in $uses
  *
- * @param string $name
+ * @param string $name Property name to check.
  * @return boolean
  */
 	public function __isset($name) {
@@ -412,8 +412,8 @@ public function __get($name) {
 /**
  * Provides backwards compatibility access for setting values to the request object.
  *
- * @param string $name
- * @param mixed $value
+ * @param string $name Property name to set.
+ * @param mixed $value Value to set.
  * @return void
  */
 	public function __set($name, $value) {
@@ -448,7 +448,7 @@ public function __set($name, $value) {
  * - $this->autoRender - To false if $request->params['return'] == 1
  * - $this->passedArgs - The the combined results of params['named'] and params['pass]
  *
- * @param CakeRequest $request
+ * @param CakeRequest $request Request instance.
  * @return void
  */
 	public function setRequest(CakeRequest $request) {
@@ -471,7 +471,7 @@ public function setRequest(CakeRequest $request) {
  * Dispatches the controller action. Checks that the action
  * exists and isn't private.
  *
- * @param CakeRequest $request
+ * @param CakeRequest $request Request instance.
  * @return mixed The resulting response.
  * @throws PrivateActionException When actions are not public or prefixed by _
  * @throws MissingActionException When actions are not defined and scaffolding is
@@ -528,7 +528,7 @@ protected function _isPrivateAction(ReflectionMethod $method, CakeRequest $reque
 /**
  * Returns a scaffold object to use for dynamically scaffolded controllers.
  *
- * @param CakeRequest $request
+ * @param CakeRequest $request Request instance.
  * @return Scaffold
  */
 	protected function _getScaffold(CakeRequest $request) {
@@ -887,11 +887,11 @@ public function validate() {
 	}
 
 /**
- * Validates models passed by parameters. Example:
+ * Validates models passed by parameters. Takes a list of models as a variable argument.
+ * Example:
  *
  * `$errors = $this->validateErrors($this->Article, $this->User);`
  *
- * @param mixed A list of models as a variable argument
  * @return array Validation errors, or false if none
  * @deprecated This method will be removed in 3.0
  */
@@ -1145,7 +1145,7 @@ public function beforeScaffold($method) {
 /**
  * Alias to beforeScaffold()
  *
- * @param string $method
+ * @param string $method Method name.
  * @return boolean
  * @see Controller::beforeScaffold()
  * @deprecated Will be removed in 3.0.
@@ -1168,7 +1168,7 @@ public function afterScaffoldSave($method) {
 /**
  * Alias to afterScaffoldSave()
  *
- * @param string $method
+ * @param string $method Method name.
  * @return boolean
  * @see Controller::afterScaffoldSave()
  * @deprecated Will be removed in 3.0.
@@ -1191,7 +1191,7 @@ public function afterScaffoldSaveError($method) {
 /**
  * Alias to afterScaffoldSaveError()
  *
- * @param string $method
+ * @param string $method Method name.
  * @return boolean
  * @see Controller::afterScaffoldSaveError()
  * @deprecated Will be removed in 3.0.
@@ -1216,7 +1216,7 @@ public function scaffoldError($method) {
 /**
  * Alias to scaffoldError()
  *
- * @param string $method
+ * @param string $method Method name.
  * @return boolean
  * @see Controller::scaffoldError()
  * @deprecated Will be removed in 3.0.

lib/Cake/Log/CakeLog.php

@@ -356,9 +356,9 @@ public static function disable($streamName) {
 /**
  * Gets the logging engine from the active streams.
  *
- * @see BaseLog
  * @param string $streamName Key name of a configured stream to get.
  * @return mixed instance of BaseLog or false if not found
+ * @see BaseLog
  */
 	public static function stream($streamName) {
 		if (empty(self::$_Collection)) {

lib/Cake/Log/CakeLogInterface.php

@@ -27,8 +27,8 @@ interface CakeLogInterface {
 /**
  * Write method to handle writes being made to the Logger
  *
- * @param string $type
- * @param string $message
+ * @param string $type Message type.
+ * @param string $message Message to write.
  * @return void
  */
 	public function write($type, $message);

lib/Cake/Log/Engine/FileLog.php

@@ -83,7 +83,7 @@ class FileLog extends BaseLog {
  * - `mask` A mask is applied when log files are created. Left empty no chmod
  *   is made.
  *
- * @param array $options Options for the FileLog, see above.
+ * @param array $config Options for the FileLog, see above.
  */
 	public function __construct($config = array()) {
 		$config = Hash::merge($this->_defaults, $config);
@@ -157,6 +157,7 @@ public function write($type, $message) {
 
 /**
  * Get filename
+ *
  * @param string $type The type of log.
  * @return string File name
  */

lib/Cake/Log/Engine/SyslogLog.php

@@ -87,7 +87,7 @@ class SyslogLog extends BaseLog {
  * Make sure the configuration contains the format parameter, by default it uses
  * the error number and the type as a prefix to the message
  *
- * @param array $config
+ * @param array $config Options list.
  */
 	public function __construct($config = array()) {
 		$config += $this->_defaults;
@@ -142,8 +142,8 @@ protected function _open($ident, $options, $facility) {
  * Extracts the call to syslog() in order to run unit tests on it. This function
  * will perform the actual write in the system logger
  *
- * @param integer $priority
- * @param string $message
+ * @param integer $priority Message priority.
+ * @param string $message Message to log.
  * @return boolean
  */
 	protected function _write($priority, $message) {