Merge pull request #3792 from dereuromark/master-docblocks

Update doc blocks regarding return $this

lib/Cake/Console/ConsoleOptionParser.php

@@ -218,7 +218,7 @@ public static function buildFromArray($spec) {
  * Get or set the command name for shell/task.
  *
  * @param string $text The text to set, or null if you want to read
- * @return mixed If reading, the value of the command. If setting $this will be returned
+ * @return string|$this If reading, the value of the command. If setting $this will be returned.
  */
 	public function command($text = null) {
 		if ($text !== null) {
@@ -233,7 +233,7 @@ public function command($text = null) {
  *
  * @param string|array $text The text to set, or null if you want to read. If an array the
  *   text will be imploded with "\n"
- * @return mixed If reading, the value of the description. If setting $this will be returned
+ * @return string|$this If reading, the value of the description. If setting $this will be returned.
  */
 	public function description($text = null) {
 		if ($text !== null) {
@@ -251,7 +251,7 @@ public function description($text = null) {
  * the options and arguments listing when help is generated.
  *
  * @param string|array $text Text when setting or null when reading. If an array the text will be imploded with "\n"
- * @return mixed If reading, the value of the epilog. If setting $this will be returned.
+ * @return string|$this If reading, the value of the epilog. If setting $this will be returned.
  */
 	public function epilog($text = null) {
 		if ($text !== null) {
@@ -284,7 +284,7 @@ public function epilog($text = null) {
  * @param ConsoleInputOption|string $name The long name you want to the value to be parsed out as when options are parsed.
  *   Will also accept an instance of ConsoleInputOption
  * @param array $options An array of parameters that define the behavior of the option
- * @return ConsoleOptionParser $this.
+ * @return $this
  */
 	public function addOption($name, $options = array()) {
 		if (is_object($name) && $name instanceof ConsoleInputOption) {
@@ -324,7 +324,7 @@ public function addOption($name, $options = array()) {
  *
  * @param ConsoleInputArgument|string $name The name of the argument. Will also accept an instance of ConsoleInputArgument
  * @param array $params Parameters for the argument, see above.
- * @return ConsoleOptionParser $this.
+ * @return $this
  */
 	public function addArgument($name, $params = array()) {
 		if (is_object($name) && $name instanceof ConsoleInputArgument) {
@@ -354,7 +354,7 @@ public function addArgument($name, $params = array()) {
  *
  * @param array $args Array of arguments to add.
  * @see ConsoleOptionParser::addArgument()
- * @return ConsoleOptionParser $this
+ * @return $this
  */
 	public function addArguments(array $args) {
 		foreach ($args as $name => $params) {
@@ -369,7 +369,7 @@ public function addArguments(array $args) {
  *
  * @param array $options Array of options to add.
  * @see ConsoleOptionParser::addOption()
- * @return ConsoleOptionParser $this
+ * @return $this
  */
 	public function addOptions(array $options) {
 		foreach ($options as $name => $params) {
@@ -391,7 +391,7 @@ public function addOptions(array $options) {
  *
  * @param ConsoleInputSubcommand|string $name Name of the subcommand. Will also accept an instance of ConsoleInputSubcommand
  * @param array $options Array of params, see above.
- * @return ConsoleOptionParser $this.
+ * @return $this
  */
 	public function addSubcommand($name, $options = array()) {
 		if (is_object($name) && $name instanceof ConsoleInputSubcommand) {
@@ -414,7 +414,7 @@ public function addSubcommand($name, $options = array()) {
  * Add multiple subcommands at once.
  *
  * @param array $commands Array of subcommands.
- * @return ConsoleOptionParser $this
+ * @return $this
  */
 	public function addSubcommands(array $commands) {
 		foreach ($commands as $name => $params) {
@@ -597,6 +597,7 @@ protected function _parseOption($name, $params) {
 			$params[$name] = $value;
 			return $params;
 		}
+		return array();
 	}
 
 /**

lib/Cake/Model/ModelValidator.php

@@ -362,7 +362,7 @@ protected function _parseRules() {
  * Sets the I18n domain for validation messages. This method is chainable.
  *
  * @param string $validationDomain [optional] The validation domain to be used.
- * @return ModelValidator
+ * @return $this
  */
 	public function setValidationDomain($validationDomain = null) {
 		if (empty($validationDomain)) {
@@ -547,7 +547,7 @@ public function count() {
  * @param string $field The name of the field where the rule is to be added
  * @param string|array|CakeValidationSet $name name of the rule to be added or list of rules for the field
  * @param array|CakeValidationRule $rule or list of rules to be added to the field's rule set
- * @return ModelValidator this instance
+ * @return $this
  */
 	public function add($field, $name, $rule = null) {
 		$this->_parseRules();
@@ -586,7 +586,7 @@ public function add($field, $name, $rule = null) {
  *
  * @param string $field The name of the field from which the rule will be removed
  * @param string $rule the name of the rule to be removed
- * @return ModelValidator this instance
+ * @return $this
  */
 	public function remove($field, $rule = null) {
 		$this->_parseRules();

lib/Cake/Model/Validator/CakeValidationSet.php

@@ -191,7 +191,7 @@ public function getRules() {
  *
  * @param string $name The name under which the rule should be set
  * @param CakeValidationRule|array $rule The validation rule to be set
- * @return CakeValidationSet this instance
+ * @return $this
  */
 	public function setRule($name, $rule) {
 		if (!($rule instanceof CakeValidationRule)) {
@@ -213,7 +213,7 @@ public function setRule($name, $rule) {
  * }}}
  *
  * @param string $name The name under which the rule should be unset
- * @return CakeValidationSet this instance
+ * @return $this
  */
 	public function removeRule($name) {
 		unset($this->_rules[$name]);
@@ -234,7 +234,7 @@ public function removeRule($name) {
  *
  * @param array $rules The rules to be set
  * @param boolean $mergeVars [optional] If true, merges vars instead of replace. Defaults to true.
- * @return ModelField
+ * @return $this
  */
 	public function setRules($rules = array(), $mergeVars = true) {
 		if ($mergeVars === false) {

lib/Cake/Network/CakeRequest.php

@@ -602,7 +602,7 @@ public function addDetector($name, $options) {
  * This modifies the parameters available through `$request->params`.
  *
  * @param array $params Array of parameters to merge in
- * @return The current object, you can chain this method.
+ * @return $this
  */
 	public function addParams($params) {
 		$this->params = array_merge($this->params, (array)$params);
@@ -614,7 +614,7 @@ public function addParams($params) {
  * Provides an easy way to modify, here, webroot and base.
  *
  * @param array $paths Array of paths to merge in
- * @return CakeRequest the current object, you can chain this method.
+ * @return $this
  */
 	public function addPaths($paths) {
 		foreach (array('webroot', 'here', 'base') as $element) {
@@ -855,7 +855,7 @@ public function query($name) {
  * will be created for you.
  *
  * @param string $name Dot separated name of the value to read/write, one or more args.
- * @return mixed Either the value being read, or this so you can chain consecutive writes.
+ * @return mixed|$this Either the value being read, or $this so you can chain consecutive writes.
  */
 	public function data($name) {
 		$args = func_get_args();

lib/Cake/Network/Email/CakeEmail.php

@@ -451,7 +451,7 @@ public function to($email = null, $name = null) {
  * @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
+ * @return $this
  */
 	public function addTo($email, $name = null) {
 		return $this->_addEmail('_to', $email, $name);
@@ -478,7 +478,7 @@ public function cc($email = null, $name = null) {
  * @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
+ * @return $this
  */
 	public function addCc($email, $name = null) {
 		return $this->_addEmail('_cc', $email, $name);
@@ -505,7 +505,7 @@ public function bcc($email = null, $name = null) {
  * @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
+ * @return $this
  */
 	public function addBcc($email, $name = null) {
 		return $this->_addEmail('_bcc', $email, $name);
@@ -545,7 +545,7 @@ public function headerCharset($charset = null) {
  * EmailPattern setter/getter
  *
  * @param string $regex for email address validation
- * @return string|CakeEmail
+ * @return string|$this
  */
 	public function emailPattern($regex = null) {
 		if ($regex === null) {
@@ -562,7 +562,7 @@ public function emailPattern($regex = null) {
  * @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
+ * @return $this
  */
 	protected function _setEmail($varName, $email, $name) {
 		if (!is_array($email)) {
@@ -610,7 +610,7 @@ protected function _validateEmail($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
+ * @return $this
  * @throws SocketException
  */
 	protected function _setEmailSingle($varName, $email, $name, $throwMessage) {
@@ -630,7 +630,7 @@ protected function _setEmailSingle($varName, $email, $name, $throwMessage) {
  * @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
+ * @return $this
  * @throws SocketException
  */
 	protected function _addEmail($varName, $email, $name) {
@@ -658,7 +658,7 @@ protected function _addEmail($varName, $email, $name) {
  * Get/Set Subject.
  *
  * @param string $subject Subject string.
- * @return string|CakeEmail
+ * @return string|$this
  */
 	public function subject($subject = null) {
 		if ($subject === null) {
@@ -672,7 +672,7 @@ public function subject($subject = null) {
  * Sets headers for the message
  *
  * @param array $headers Associative array containing headers to be set.
- * @return CakeEmail $this
+ * @return $this
  * @throws SocketException
  */
 	public function setHeaders($headers) {
@@ -687,7 +687,7 @@ public function setHeaders($headers) {
  * Add header for the message
  *
  * @param array $headers Headers to set.
- * @return object $this
+ * @return $this
  * @throws SocketException
  */
 	public function addHeaders($headers) {
@@ -820,7 +820,7 @@ protected function _formatAddress($address) {
  *
  * @param boolean|string $template Template name or null to not use
  * @param boolean|string $layout Layout name or null to not use
- * @return array|CakeEmail
+ * @return array|$this
  */
 	public function template($template = false, $layout = false) {
 		if ($template === false) {
@@ -840,7 +840,7 @@ public function template($template = false, $layout = false) {
  * View class for render
  *
  * @param string $viewClass View class name.
- * @return string|CakeEmail
+ * @return string|$this
  */
 	public function viewRender($viewClass = null) {
 		if ($viewClass === null) {
@@ -854,7 +854,7 @@ public function viewRender($viewClass = null) {
  * Variables to be set on render
  *
  * @param array $viewVars Variables to set for view.
- * @return array|CakeEmail
+ * @return array|$this
  */
 	public function viewVars($viewVars = null) {
 		if ($viewVars === null) {
@@ -868,7 +868,7 @@ public function viewVars($viewVars = null) {
  * Theme to use when rendering
  *
  * @param string $theme Theme name.
- * @return string|CakeEmail
+ * @return string|$this
  */
 	public function theme($theme = null) {
 		if ($theme === null) {
@@ -882,7 +882,7 @@ public function theme($theme = null) {
  * Helpers to be used in render
  *
  * @param array $helpers Helpers list.
- * @return array|CakeEmail
+ * @return array|$this
  */
 	public function helpers($helpers = null) {
 		if ($helpers === null) {
@@ -896,7 +896,7 @@ public function helpers($helpers = null) {
  * Email format
  *
  * @param string $format Formatting string.
- * @return string|CakeEmail
+ * @return string|$this
  * @throws SocketException
  */
 	public function emailFormat($format = null) {
@@ -914,7 +914,7 @@ public function emailFormat($format = null) {
  * Transport name
  *
  * @param string $name Transport name.
- * @return string|CakeEmail
+ * @return string|$this
  */
 	public function transport($name = null) {
 		if ($name === null) {
@@ -928,7 +928,7 @@ public function transport($name = null) {
 /**
  * Return the transport class
  *
- * @return CakeEmail
+ * @return AbstractTransport
  * @throws SocketException
  */
 	public function transportClass() {
@@ -951,7 +951,7 @@ public function transportClass() {
  * Message-ID
  *
  * @param boolean|string $message True to generate a new Message-ID, False to ignore (not send in email), String to set as Message-ID
- * @return boolean|string|CakeEmail
+ * @return boolean|string|$this
  * @throws SocketException
  */
 	public function messageId($message = null) {
@@ -973,7 +973,7 @@ public function messageId($message = null) {
  * Domain as top level (the part after @)
  *
  * @param string $domain Manually set the domain for CLI mailing
- * @return string|CakeEmail
+ * @return string|$this
  */
 	public function domain($domain = null) {
 		if ($domain === null) {
@@ -1027,7 +1027,7 @@ public function domain($domain = null) {
  * attachment compatibility with outlook email clients.
  *
  * @param string|array $attachments String with the filename or array with filenames
- * @return array|CakeEmail Either the array of attachments when getting or $this when setting.
+ * @return array|$this Either the array of attachments when getting or $this when setting.
  * @throws SocketException
  */
 	public function attachments($attachments = null) {
@@ -1070,7 +1070,7 @@ public function attachments($attachments = null) {
  * Add attachments
  *
  * @param string|array $attachments String with the filename or array with filenames
- * @return CakeEmail $this
+ * @return $this
  * @throws SocketException
  * @see CakeEmail::attachments()
  */
@@ -1111,7 +1111,7 @@ public function message($type = null) {
  * `$email->config(array('to' => 'bill@example.com'));`
  *
  * @param string|array $config String with configuration name (from email.php), array with config or null to return current config
- * @return string|array|CakeEmail
+ * @return string|array|$this
  */
 	public function config($config = null) {
 		if ($config === null) {
@@ -1259,7 +1259,7 @@ protected function _applyConfig($config) {
 /**
  * Reset all CakeEmail internal variables to be able to send out a new email.
  *
- * @return CakeEmail $this
+ * @return $this
  */
 	public function reset() {
 		$this->_to = array();
@@ -1696,7 +1696,7 @@ protected function _renderTemplates($content) {
 /**
  * Return the Content-Transfer Encoding value based on the set charset
  *
- * @return void
+ * @return string
  */
 	protected function _getContentTransferEncoding() {
 		$charset = strtoupper($this->charset);