Fix API docblock CS errors.

lib/Cake/Model/BehaviorCollection.php

@@ -54,8 +54,8 @@ class BehaviorCollection extends ObjectCollection implements CakeEventListener {
 /**
  * Attaches a model object and loads a list of behaviors
  *
- * @param string $modelName
- * @param array $behaviors
+ * @param string $modelName Model name.
+ * @param array $behaviors Behaviors list.
  * @return void
  */
 	public function init($modelName, $behaviors = array()) {
@@ -71,8 +71,8 @@ class BehaviorCollection extends ObjectCollection implements CakeEventListener {
 /**
  * Backwards compatible alias for load()
  *
- * @param string $behavior
- * @param array $config
+ * @param string $behavior Behavior name.
+ * @param array $config Configuration options.
  * @return void
  * @deprecated Will be removed in 3.0. Replaced with load().
  */

lib/Cake/Model/Datasource/CakeSession.php

@@ -277,7 +277,7 @@ class CakeSession {
 /**
  * Used to write new data to _SESSION, since PHP doesn't like us setting the _SESSION var itself.
  *
- * @param array $old Set of old variables => values
+ * @param array &$old Set of old variables => values
  * @param array $new New set of variable => value
  * @return void
  */
@@ -547,6 +547,7 @@ class CakeSession {
 
 /**
  * Returns whether a session exists
+ *
  * @return boolean
  */
 	protected static function _hasSession() {
@@ -556,7 +557,7 @@ class CakeSession {
 /**
  * Find the handler class and make sure it implements the correct interface.
  *
- * @param string $handler
+ * @param string $handler Handler name.
  * @return void
  * @throws CakeSessionException
  */
@@ -576,7 +577,7 @@ class CakeSession {
 /**
  * Get one of the prebaked default session configurations.
  *
- * @param string $name
+ * @param string $name Config name.
  * @return boolean|array
  */
 	protected static function _defaultConfig($name) {

lib/Cake/Model/Model.php

@@ -1063,7 +1063,7 @@ class Model extends Object implements CakeEventListener {
  * Build an array-based association from string.
  *
  * @param string $type 'belongsTo', 'hasOne', 'hasMany', 'hasAndBelongsToMany'
- * @param string $assocKey
+ * @param string $assocKey Association key.
  * @return void
  */
 	protected function _generateAssociation($type, $assocKey) {
@@ -1214,7 +1214,7 @@ class Model extends Object implements CakeEventListener {
 /**
  * Move values to alias
  *
- * @param array $data
+ * @param array $data Data.
  * @return array
  */
 	protected function _setAliasData($data) {
@@ -1892,7 +1892,7 @@ class Model extends Object implements CakeEventListener {
  *
  * @param array $joined Data to save
  * @param integer|string $id ID of record in this model
- * @param DataSource $db
+ * @param DataSource $db Datasource instance.
  * @return void
  */
 	protected function _saveMulti($joined, $id, $db) {
@@ -2285,7 +2285,7 @@ class Model extends Object implements CakeEventListener {
  * If you do not want this to happen, make a copy of `$data` before passing it
  * to this method
  *
- * @param array $data Record data to validate. This should be a numerically-indexed array
+ * @param array &$data Record data to validate. This should be a numerically-indexed array
  * @param array $options Options to use when validating record data (see above), See also $options of validates().
  * @return boolean|array If atomic: True on success, or false on failure.
  *    Otherwise: array similar to the $data array passed, but values are set to true/false
@@ -2485,7 +2485,7 @@ class Model extends Object implements CakeEventListener {
  * Helper method for saveAll() and friends, to add foreign key to fieldlist
  *
  * @param string $key fieldname to be added to list
- * @param array $options
+ * @param array $options Options list
  * @return array $options
  */
 	protected function _addToWhiteList($key, $options) {
@@ -2520,7 +2520,7 @@ class Model extends Object implements CakeEventListener {
  * If you do not want this to happen, make a copy of `$data` before passing it
  * to this method
  *
- * @param array $data Record data to validate. This should be an array indexed by association name.
+ * @param array &$data Record data to validate. This should be an array indexed by association name.
  * @param array $options Options to use when validating record data (see above), See also $options of validates().
  * @return array|boolean If atomic: True on success, or false on failure.
  *    Otherwise: array similar to the $data array passed, but values are set to true/false
@@ -2744,7 +2744,7 @@ class Model extends Object implements CakeEventListener {
 /**
  * Collects foreign keys from associations.
  *
- * @param string $type
+ * @param string $type Association type.
  * @return array
  */
 	protected function _collectForeignKeys($type = 'belongsTo') {
@@ -2970,8 +2970,8 @@ class Model extends Object implements CakeEventListener {
  * Handles the before/after filter logic for find('all') operations. Only called by Model::find().
  *
  * @param string $state Either "before" or "after"
- * @param array $query
- * @param array $results
+ * @param array $query Query.
+ * @param array $results Results.
  * @return array
  * @see Model::find()
  */
@@ -2987,8 +2987,8 @@ class Model extends Object implements CakeEventListener {
  * Handles the before/after filter logic for find('first') operations. Only called by Model::find().
  *
  * @param string $state Either "before" or "after"
- * @param array $query
- * @param array $results
+ * @param array $query Query.
+ * @param array $results Results.
  * @return array
  * @see Model::find()
  */
@@ -3009,8 +3009,8 @@ class Model extends Object implements CakeEventListener {
  * Handles the before/after filter logic for find('count') operations. Only called by Model::find().
  *
  * @param string $state Either "before" or "after"
- * @param array $query
- * @param array $results
+ * @param array $query Query.
+ * @param array $results Results.
  * @return integer The number of records found, or false
  * @see Model::find()
  */
@@ -3061,8 +3061,8 @@ class Model extends Object implements CakeEventListener {
  * Handles the before/after filter logic for find('list') operations. Only called by Model::find().
  *
  * @param string $state Either "before" or "after"
- * @param array $query
- * @param array $results
+ * @param array $query Query.
+ * @param array $results Results.
  * @return array Key/value pairs of primary keys/display field values of all records found
  * @see Model::find()
  */
@@ -3122,8 +3122,8 @@ class Model extends Object implements CakeEventListener {
  * rows and return them.
  *
  * @param string $state Either "before" or "after"
- * @param array $query
- * @param array $results
+ * @param array $query Query.
+ * @param array $results Results.
  * @return array
  */
 	protected function _findNeighbors($state, $query, $results = array()) {
@@ -3183,9 +3183,9 @@ class Model extends Object implements CakeEventListener {
  * In the event of ambiguous results returned (multiple top level results, with different parent_ids)
  * top level results with different parent_ids to the first result will be dropped
  *
- * @param string $state
- * @param mixed $query
- * @param array $results
+ * @param string $state Either "before" or "after".
+ * @param array $query Query.
+ * @param array $results Results.
  * @return array Threaded results
  */
 	protected function _findThreaded($state, $query, $results = array()) {
@@ -3295,11 +3295,14 @@ class Model extends Object implements CakeEventListener {
 /**
  * Returns a resultset for a given SQL statement. Custom SQL queries should be performed with this method.
  *
- * @param string $sql SQL statement
- * @param boolean|array $params Either a boolean to control query caching or an array of parameters
+ * The method can options 2nd and 3rd parameters.
+ *
+ * - 2nd param: Either a boolean to control query caching or an array of parameters
  *    for use with prepared statement placeholders.
- * @param boolean $cache If $params is provided, a boolean flag for enabling/disabled
- *    query caching.
+ * - 3rd param: If 2nd argument is provided, a boolean flag for enabling/disabled
+ *   query caching.
+ *
+ * @param string $sql SQL statement
  * @return mixed Resultset array or boolean indicating success / failure depending on the query executed
  * @link http://book.cakephp.org/2.0/en/models/retrieving-your-data.html#model-query
  */
@@ -3723,7 +3726,7 @@ class Model extends Object implements CakeEventListener {
 /**
  * Returns an instance of a model validator for this class
  *
- * @param ModelValidator Model validator instance.
+ * @param ModelValidator $instance Model validator instance.
  *  If null a new ModelValidator instance will be made using current model object
  * @return ModelValidator
  */

lib/Cake/Network/Email/AbstractTransport.php

@@ -33,7 +33,7 @@ abstract class AbstractTransport {
 /**
  * Send mail
  *
- * @param CakeEmail $email
+ * @param CakeEmail $email CakeEmail instance.
  * @return array
  */
 	abstract public function send(CakeEmail $email);
@@ -41,7 +41,7 @@ abstract class AbstractTransport {
 /**
  * Set the config
  *
- * @param array $config
+ * @param array $config Configuration options.
  * @return array Returns configs
  */
 	public function config($config = null) {
@@ -55,7 +55,7 @@ abstract class AbstractTransport {
  * Help to convert headers in string
  *
  * @param array $headers Headers in format key => value
- * @param string $eol
+ * @param string $eol End of line string.
  * @return string
  */
 	protected function _headersToString($headers, $eol = "\r\n") {

lib/Cake/Network/Email/CakeEmail.php

@@ -353,8 +353,9 @@ class CakeEmail {
 /**
  * From
  *
- * @param string|array $email
- * @param string $name
+ * @param string|array $email Null to get, String with email,
+ *   Array with email as key, name as value or email as value (without name)
+ * @param string $name Name
  * @return array|CakeEmail
  * @throws SocketException
  */
@@ -368,8 +369,9 @@ class CakeEmail {
 /**
  * Sender
  *
- * @param string|array $email
- * @param string $name
+ * @param string|array $email Null to get, String with email,
+ *   Array with email as key, name as value or email as value (without name)
+ * @param string $name Name
  * @return array|CakeEmail
  * @throws SocketException
  */
@@ -383,8 +385,9 @@ class CakeEmail {
 /**
  * Reply-To
  *
- * @param string|array $email
- * @param string $name
+ * @param string|array $email Null to get, String with email,
+ *   Array with email as key, name as value or email as value (without name)
+ * @param string $name Name
  * @return array|CakeEmail
  * @throws SocketException
  */
@@ -398,8 +401,9 @@ class CakeEmail {
 /**
  * Read Receipt (Disposition-Notification-To header)
  *
- * @param string|array $email
- * @param string $name
+ * @param string|array $email Null to get, String with email,
+ *   Array with email as key, name as value or email as value (without name)
+ * @param string $name Name
  * @return array|CakeEmail
  * @throws SocketException
  */
@@ -413,8 +417,9 @@ class CakeEmail {
 /**
  * Return Path
  *
- * @param string|array $email
- * @param string $name
+ * @param string|array $email Null to get, String with email,
+ *   Array with email as key, name as value or email as value (without name)
+ * @param string $name Name
  * @return array|CakeEmail
  * @throws SocketException
  */
@@ -428,8 +433,9 @@ class CakeEmail {
 /**
  * To
  *
- * @param string|array $email Null to get, String with email, Array with email as key, name as value or email as value (without name)
- * @param string $name
+ * @param string|array $email Null to get, String with email,
+ *   Array with email as key, name as value or email as value (without name)
+ * @param string $name Name
  * @return array|CakeEmail
  */
 	public function to($email = null, $name = null) {
@@ -442,8 +448,9 @@ class CakeEmail {
 /**
  * Add To
  *
- * @param string|array $email String with email, Array with email as key, name as value or email as value (without name)
- * @param string $name
+ * @param string|array $email Null to get, String with email,
+ *   Array with email as key, name as value or email as value (without name)
+ * @param string $name Name
  * @return CakeEmail $this
  */
 	public function addTo($email, $name = null) {
@@ -453,8 +460,9 @@ class CakeEmail {
 /**
  * Cc
  *
- * @param string|array $email String with email, Array with email as key, name as value or email as value (without name)
- * @param string $name
+ * @param string|array $email Null to get, String with email,
+ *   Array with email as key, name as value or email as value (without name)
+ * @param string $name Name
  * @return array|CakeEmail
  */
 	public function cc($email = null, $name = null) {
@@ -467,8 +475,9 @@ class CakeEmail {
 /**
  * Add Cc
  *
- * @param string|array $email String with email, Array with email as key, name as value or email as value (without name)
- * @param string $name
+ * @param string|array $email Null to get, String with email,
+ *   Array with email as key, name as value or email as value (without name)
+ * @param string $name Name
  * @return CakeEmail $this
  */
 	public function addCc($email, $name = null) {
@@ -478,8 +487,9 @@ class CakeEmail {
 /**
  * Bcc
  *
- * @param string|array $email String with email, Array with email as key, name as value or email as value (without name)
- * @param string $name
+ * @param string|array $email Null to get, String with email,
+ *   Array with email as key, name as value or email as value (without name)
+ * @param string $name Name
  * @return array|CakeEmail
  */
 	public function bcc($email = null, $name = null) {
@@ -492,8 +502,9 @@ class CakeEmail {
 /**
  * Add Bcc
  *
- * @param string|array $email String with email, Array with email as key, name as value or email as value (without name)
- * @param string $name
+ * @param string|array $email Null to get, String with email,
+ *   Array with email as key, name as value or email as value (without name)
+ * @param string $name Name
  * @return CakeEmail $this
  */
 	public function addBcc($email, $name = null) {
@@ -503,7 +514,7 @@ class CakeEmail {
 /**
  * Charset setter/getter
  *
- * @param string $charset
+ * @param string $charset Character set.
  * @return string $this->charset
  */
 	public function charset($charset = null) {
@@ -520,7 +531,7 @@ class CakeEmail {
 /**
  * HeaderCharset setter/getter
  *
- * @param string $charset
+ * @param string $charset Character set.
  * @return string $this->charset
  */
 	public function headerCharset($charset = null) {
@@ -547,9 +558,10 @@ class CakeEmail {
 /**
  * Set email
  *
- * @param string $varName
- * @param string|array $email
- * @param string $name
+ * @param string $varName Property name
+ * @param string|array $email String with email,
+ *   Array with email as key, name as value or email as value (without name)
+ * @param string $name Name
  * @return CakeEmail $this
  */
 	protected function _setEmail($varName, $email, $name) {
@@ -576,7 +588,7 @@ class CakeEmail {
 /**
  * Validate email address
  *
- * @param string $email
+ * @param string $email Email
  * @return void
  * @throws SocketException If email address does not validate
  */
@@ -593,10 +605,11 @@ class CakeEmail {
 /**
  * Set only 1 email
  *
- * @param string $varName
- * @param string|array $email
- * @param string $name
- * @param string $throwMessage
+ * @param string $varName Property name
+ * @param string|array $email String with email,
+ *   Array with email as key, name as value or email as value (without name)
+ * @param string $name Name
+ * @param string $throwMessage Exception message
  * @return CakeEmail $this
  * @throws SocketException
  */
@@ -613,9 +626,10 @@ class CakeEmail {
 /**
  * Add email
  *
- * @param string $varName
- * @param string|array $email
- * @param string $name
+ * @param string $varName Property name
+ * @param string|array $email String with email,
+ *   Array with email as key, name as value or email as value (without name)
+ * @param string $name Name
  * @return CakeEmail $this
  * @throws SocketException
  */
@@ -643,7 +657,7 @@ class CakeEmail {
 /**
  * Get/Set Subject.
  *
- * @param string $subject
+ * @param string $subject Subject string.
  * @return string|CakeEmail
  */
 	public function subject($subject = null) {
@@ -672,7 +686,7 @@ class CakeEmail {
 /**
  * Add header for the message
  *
- * @param array $headers
+ * @param array $headers Headers to set.
  * @return object $this
  * @throws SocketException
  */
@@ -698,14 +712,19 @@ class CakeEmail {
  * - `bcc`
  * - `subject`
  *
- * @param array $include
+ * @param array $include List of headers.
  * @return array
  */
 	public function getHeaders($include = array()) {
 		if ($include == array_values($include)) {
 			$include = array_fill_keys($include, true);
 		}
-		$defaults = array_fill_keys(array('from', 'sender', 'replyTo', 'readReceipt', 'returnPath', 'to', 'cc', 'bcc', 'subject'), false);
+		$defaults = array_fill_keys(
+			array(
+				'from', 'sender', 'replyTo', 'readReceipt', 'returnPath',
+				'to', 'cc', 'bcc', 'subject'),
+			false
+		);
 		$include += $defaults;
 
 		$headers = array();
@@ -777,7 +796,7 @@ class CakeEmail {
  * be quoted as characters like `:` and `,` are known to cause issues
  * in address header fields.
  *
- * @param array $address
+ * @param array $address Addresses to format.
  * @return array
  */
 	protected function _formatAddress($address) {
@@ -820,7 +839,7 @@ class CakeEmail {
 /**
  * View class for render
  *
- * @param string $viewClass
+ * @param string $viewClass View class name.
  * @return string|CakeEmail
  */
 	public function viewRender($viewClass = null) {
@@ -834,7 +853,7 @@ class CakeEmail {
 /**
  * Variables to be set on render
  *
- * @param array $viewVars
+ * @param array $viewVars Variables to set for view.
  * @return array|CakeEmail
  */
 	public function viewVars($viewVars = null) {
@@ -848,7 +867,7 @@ class CakeEmail {
 /**
  * Theme to use when rendering
  *
- * @param string $theme
+ * @param string $theme Theme name.
  * @return string|CakeEmail
  */
 	public function theme($theme = null) {
@@ -862,7 +881,7 @@ class CakeEmail {
 /**
  * Helpers to be used in render
  *
- * @param array $helpers
+ * @param array $helpers Helpers list.
  * @return array|CakeEmail
  */
 	public function helpers($helpers = null) {
@@ -876,7 +895,7 @@ class CakeEmail {
 /**
  * Email format
  *
- * @param string $format
+ * @param string $format Formatting string.
  * @return string|CakeEmail
  * @throws SocketException
  */
@@ -894,7 +913,7 @@ class CakeEmail {
 /**
  * Transport name
  *
- * @param string $name
+ * @param string $name Transport name.
  * @return string|CakeEmail
  */
 	public function transport($name = null) {
@@ -1185,7 +1204,7 @@ class CakeEmail {
 /**
  * Apply the config to an instance
  *
- * @param array $config
+ * @param array $config Configuration options.
  * @return void
  * @throws ConfigureException When configuration file cannot be found, or is missing
  *   the named config.

lib/Cake/Network/Email/SmtpTransport.php

@@ -104,7 +104,7 @@ class SmtpTransport extends AbstractTransport {
 /**
  * Set the configuration
  *
- * @param array $config
+ * @param array $config Configuration options.
  * @return array Returns configs
  */
 	public function config($config = null) {
@@ -127,7 +127,7 @@ class SmtpTransport extends AbstractTransport {
 /**
  * Parses and stores the reponse lines in `'code' => 'message'` format.
  *
- * @param array $responseLines
+ * @param array $responseLines Response lines to parse.
  * @return void
  */
 	protected function _bufferResponseLines(array $responseLines) {

lib/Cake/Utility/Sanitize.php

@@ -184,7 +184,7 @@ class Sanitize {
  *
  * Will remove all `<b>`, `<p>`, and `<div>` tags from the $dirty string.
  *
- * @param string $str,... String to sanitize
+ * @param string $str String to sanitize.
  * @return string sanitized String
  */
 	public static function stripTags($str) {

lib/Cake/Utility/Set.php

@@ -120,7 +120,7 @@ class Set {
  * returned object (recursively). If $key is numeric will maintain array
  * structure
  *
- * @param array $array Array to map
+ * @param array &$array Array to map
  * @param string $class Class name
  * @param boolean $primary whether to assign first array key as the _name_
  * @return mixed Mapped object
@@ -458,7 +458,7 @@ class Set {
  * @param string|array $conditions An array of condition strings or an XPath expression
  * @param array $data An array of data to execute the match on
  * @param integer $i Optional: The 'nth'-number of the item being matched.
- * @param integer $length
+ * @param integer $length Length.
  * @return boolean
  * @link http://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::matches
  */
@@ -851,6 +851,7 @@ class Set {
 
 /**
  * Converts an object into an array.
+ *
  * @param object $object Object to reverse
  * @return array Array representation of given object
  * @link http://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::reverse
@@ -926,8 +927,8 @@ class Set {
 /**
  * Flattens an array for sorting
  *
- * @param array $results
- * @param string $key
+ * @param array $results Array to flatten.
+ * @param string $key Key.
  * @return array
  */
 	protected static function _flatten($results, $key = null) {
@@ -1026,7 +1027,7 @@ class Set {
 /**
  * Takes in a flat array and returns a nested array
  *
- * @param mixed $data
+ * @param mixed $data Data
  * @param array $options Options are:
  *      children   - the key name to use in the resultset for children
  *      idPath     - the path to a key that identifies each entry

lib/Cake/Utility/String.php

@@ -253,8 +253,8 @@ class String {
  * is to replace all whitespace and unneeded markup around placeholders that did not get replaced
  * by String::insert().
  *
- * @param string $str
- * @param array $options
+ * @param string $str String to clean.
+ * @param array $options Options list.
  * @return string
  * @see String::insert()
  */