Merge pull request #5162 from cakephp/3.0-cleanup

Consolidate doc block lines around chaining.

src/Database/Expression/FunctionExpression.php

@@ -68,7 +68,7 @@ class FunctionExpression extends QueryExpression {
  * if no value is passed it will return current name
  *
  * @param string $name The name of the function
- * @return string
+ * @return string|$this
  */
 	public function name($name = null) {
 		if ($name === null) {
@@ -87,7 +87,7 @@ class FunctionExpression extends QueryExpression {
  * passed arguments
  * @param bool $prepend Whether to prepend or append to the list of arguments
  * @see FunctionExpression::__construct() for more details.
- * @return FunctionExpression
+ * @return $this
  */
 	public function add($params, $types = [], $prepend = false) {
 		$put = $prepend ? 'array_unshift' : 'array_push';

src/Database/Expression/ValuesExpression.php

@@ -93,7 +93,7 @@ class ValuesExpression implements ExpressionInterface {
  * the currently stored columns
  *
  * @param array $cols arrays with columns to be inserted
- * @return array|ValuesExpression
+ * @return array|$this
  */
 	public function columns($cols = null) {
 		if ($cols === null) {
@@ -108,7 +108,7 @@ class ValuesExpression implements ExpressionInterface {
  * the currently stored values
  *
  * @param array $values arrays with values to be inserted
- * @return array|ValuesExpression
+ * @return array|$this
  */
 	public function values($values = null) {
 		if ($values === null) {

src/Database/Schema/Table.php

@@ -279,7 +279,7 @@ class Table {
  *
  * @param string $name The name of the column
  * @param array $attrs The attributes for the column.
- * @return Table this
+ * @return $this
  */
 	public function addColumn($name, $attrs) {
 		if (is_string($attrs)) {
@@ -362,7 +362,7 @@ class Table {
  *
  * @param string $name The name of the index.
  * @param array $attrs The attributes for the index.
- * @return Table this
+ * @return $this
  * @throws \Cake\Database\Exception
  */
 	public function addIndex($name, $attrs) {
@@ -449,7 +449,7 @@ class Table {
  *
  * @param string $name The name of the constraint.
  * @param array $attrs The attributes for the constraint.
- * @return Table this
+ * @return $this
  * @throws \Cake\Database\Exception
  */
 	public function addConstraint($name, $attrs) {

src/Datasource/EntityTrait.php

@@ -205,7 +205,7 @@ trait EntityTrait {
  * first argument is also an array, in which case will be treated as $options
  * @param array $options options to be used for setting the property. Allowed option
  * keys are `setter` and `guard`
- * @return \Cake\Datasource\EntityInterface this object
+ * @return $this
  * @throws \InvalidArgumentException
  */
 	public function set($property, $value = null, $options = []) {
@@ -307,7 +307,7 @@ trait EntityTrait {
  * $entity->has('last_name'); // false
  * }}}
  *
- * When checking multiple properties. All properties must not be null 
+ * When checking multiple properties. All properties must not be null
  * in order for true to be returned.
  *
  * @param string|array $property The property or properties to check.
@@ -333,7 +333,7 @@ trait EntityTrait {
  * }}}
  *
  * @param string|array $property The property to unset.
- * @return \Cake\DataSource\EntityInterface
+ * @return $this
  */
 	public function unsetProperty($property) {
 		$property = (array)$property;
@@ -352,7 +352,7 @@ trait EntityTrait {
  * will be returned. Otherwise the hidden properties will be set.
  *
  * @param null|array $properties Either an array of properties to hide or null to get properties
- * @return array|\Cake\DataSource\EntityInterface
+ * @return array|$this
  */
 	public function hiddenProperties($properties = null) {
 		if ($properties === null) {
@@ -369,7 +369,7 @@ trait EntityTrait {
  * will be returned. Otherwise the virtual properties will be set.
  *
  * @param null|array $properties Either an array of properties to treat as virtual or null to get properties
- * @return array|\Cake\DataSource\EntityInterface
+ * @return array|$this
  */
 	public function virtualProperties($properties = null) {
 		if ($properties === null) {
@@ -630,7 +630,7 @@ trait EntityTrait {
  *
  * @param string|array $field The field to get errors for, or the array of errors to set.
  * @param string|array $errors The errors to be set for $field
- * @return array|\Cake\Datasource\EntityInterface
+ * @return array|$this
  */
 	public function errors($field = null, $errors = null) {
 		if ($field === null) {
@@ -750,7 +750,7 @@ trait EntityTrait {
  * @param string|array $property single or list of properties to change its accessibility
  * @param bool $set true marks the property as accessible, false will
  * mark it as protected.
- * @return \Cake\Datasource\EntityInterface|bool
+ * @return $this|bool
  */
 	public function accessible($property, $set = null) {
 		if ($set === null) {

src/Datasource/QueryTrait.php

@@ -88,7 +88,7 @@ trait QueryTrait {
  * and this query object will be returned for chaining.
  *
  * @param \Cake\Datasource\RepositoryInterface $table The default table object to use
- * @return \Cake\Datasource\RepositoryInterface|\Cake\ORM\Query
+ * @return \Cake\Datasource\RepositoryInterface|$this
  */
 	public function repository(RepositoryInterface $table = null) {
 		if ($table === null) {
@@ -108,7 +108,7 @@ trait QueryTrait {
  * This method is most useful when combined with results stored in a persistent cache.
  *
  * @param \Cake\Datasource\ResultSetInterface $results The results this query should return.
- * @return \Cake\ORM\Query The query instance.
+ * @return $this The query instance.
  */
 	public function setResult($results) {
 		$this->_results = $results;
@@ -161,7 +161,7 @@ trait QueryTrait {
  *   When using a function, this query instance will be supplied as an argument.
  * @param string|\Cake\Cache\CacheEngine $config Either the name of the cache config to use, or
  *   a cache config instance.
- * @return \Cake\Datasource\QueryTrait This same object
+ * @return $this This instance
  */
 	public function cache($key, $config = 'default') {
 		if ($key === false) {
@@ -177,7 +177,7 @@ trait QueryTrait {
  * passed, the current configured query `_eagerLoaded` value is returned.
  *
  * @param bool $value Whether or not to eager load.
- * @return \Cake\ORM\Query
+ * @return $this|\Cake\ORM\Query
  */
 	public function eagerLoaded($value = null) {
 		if ($value === null) {
@@ -248,7 +248,7 @@ trait QueryTrait {
  * @param callable $mapper The mapper callable.
  * @param callable $reducer The reducing function.
  * @param bool $overwrite Set to true to overwrite existing map + reduce functions.
- * @return \Cake\Datasource\QueryTrait|array
+ * @return $this|array
  * @see \Cake\Collection\Iterator\MapReduce for details on how to use emit data to the map reducer.
  */
 	public function mapReduce(callable $mapper = null, callable $reducer = null, $overwrite = false) {
@@ -299,7 +299,7 @@ trait QueryTrait {
  *
  * @param callable $formatter The formatting callable.
  * @param bool|int $mode Whether or not to overwrite, append or prepend the formatter.
- * @return \Cake\Datasource\QueryTrait|array
+ * @return $this|array
  */
 	public function formatResults(callable $formatter = null, $mode = 0) {
 		if ($mode === self::OVERWRITE) {
@@ -378,7 +378,7 @@ trait QueryTrait {
  * This is handy for passing all query clauses at once.
  *
  * @param array $options the options to be applied
- * @return \Cake\Datasource\QueryTrait this object
+ * @return $this This object
  */
 	abstract public function applyOptions(array $options);
 

src/Model/Behavior/Translate/TranslateTrait.php

@@ -29,7 +29,7 @@ trait TranslateTrait {
  * it.
  *
  * @param string $language Language to return entity for.
- * @return \Cake\ORM\Entity
+ * @return $this|\Cake\ORM\Entity
  */
 	public function translation($language) {
 		if ($language === $this->get('_locale')) {

src/Network/Http/FormData.php

@@ -74,7 +74,7 @@ class FormData implements \Countable {
  *
  * @param string $name The name of the part.
  * @param mixed $value The value for the part.
- * @return FormData this
+ * @return $this
  */
 	public function add($name, $value) {
 		if (is_array($value)) {
@@ -95,7 +95,7 @@ class FormData implements \Countable {
  * Iterates the parameter and adds all the key/values.
  *
  * @param array $data Array of data to add.
- * @return FormData this
+ * @return $this
  */
 	public function addMany(array $data) {
 		foreach ($data as $name => $value) {

src/Network/Http/Request.php

@@ -59,7 +59,7 @@ class Request extends Message {
  * Get/Set the HTTP method.
  *
  * @param string|null $method The method for the request.
- * @return mixed Either this or the current method.
+ * @return $this|string Either this or the current method.
  * @throws \Cake\Core\Exception\Exception On invalid methods.
  */
 	public function method($method = null) {
@@ -78,7 +78,7 @@ class Request extends Message {
  * Get/Set the url for the request.
  *
  * @param string|null $url The url for the request. Leave null for get
- * @return mixed Either $this or the url value.
+ * @return $this|string Either $this or the url value.
  */
 	public function url($url = null) {
 		if ($url === null) {

src/Network/Request.php

@@ -1087,7 +1087,7 @@ class Request implements \ArrayAccess {
  *
  * @param string $key The key you want to read/write from/to.
  * @param string $value Value to set. Default null.
- * @return null|string|\Cake\Network\Request Request instance if used as setter,
+ * @return $this|string|null This instance if used as setter,
  *   if used as getter either the environment value, or null if the value doesn't exist.
  */
 	public function env($key, $value = null) {

src/Routing/Router.php

@@ -851,8 +851,7 @@ class Router {
  *   If you have no parameters, this argument can be a callable.
  * @param callable $callback The callback to invoke with the scoped collection.
  * @throws \InvalidArgumentException When an invalid callable is provided.
- * @return null|\Cake\Routing\RouteBuilder The route builder
- *   was created/used.
+ * @return void
  */
 	public static function scope($path, $params = [], $callback = null) {
 		$builder = new RouteBuilder(static::$_collection, '/', [], [

src/Validation/ValidationSet.php

@@ -108,7 +108,7 @@ class ValidationSet implements \ArrayAccess, \IteratorAggregate, \Countable {
  *
  * @param string $name The name under which the rule should be set
  * @param \Cake\Validation\ValidationRule|array $rule The validation rule to be set
- * @return \Cake\Validation\ValidationSet this instance
+ * @return $this
  */
 	public function add($name, $rule) {
 		if (!($rule instanceof ValidationRule)) {
@@ -130,7 +130,7 @@ class ValidationSet implements \ArrayAccess, \IteratorAggregate, \Countable {
  * }}}
  *
  * @param string $name The name under which the rule should be unset
- * @return \Cake\Validation\ValidationSet this instance
+ * @return $this
  */
 	public function remove($name) {
 		unset($this->_rules[$name]);

src/Validation/Validator.php

@@ -170,7 +170,7 @@ class Validator implements \ArrayAccess, \IteratorAggregate, \Countable {
  *
  * @param string $name  The name under which the provider should be set.
  * @param null|object|string $object Provider object or class name.
- * @return Validator|object|string|null
+ * @return $this|object|string|null
  */
 	public function provider($name, $object = null) {
 		if ($object === null) {
@@ -272,7 +272,7 @@ class Validator implements \ArrayAccess, \IteratorAggregate, \Countable {
  * @param string $field The name of the field from which the rule will be removed
  * @param array|string $name The alias for a single rule or multiple rules array
  * @param array|\Cake\Validation\ValidationRule $rule the rule to add
- * @return Validator this instance
+ * @return $this
  */
 	public function add($field, $name, $rule = []) {
 		$field = $this->field($field);
@@ -303,7 +303,7 @@ class Validator implements \ArrayAccess, \IteratorAggregate, \Countable {
  *
  * @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 Validator this instance
+ * @return $this
  */
 	public function remove($field, $rule = null) {
 		if ($rule === null) {
@@ -320,7 +320,7 @@ class Validator implements \ArrayAccess, \IteratorAggregate, \Countable {
  * @param string $field the name of the field
  * @param bool|string $mode Valid values are true, false, 'create', 'update'
  * @param string $message The message to show if the field presence validation fails.
- * @return Validator this instance
+ * @return $this
  */
 	public function requirePresence($field, $mode = true, $message = null) {
 		$this->field($field)->isPresenceRequired($mode);
@@ -338,7 +338,7 @@ class Validator implements \ArrayAccess, \IteratorAggregate, \Countable {
  * @param string $field the name of the field
  * @param bool|string $mode Valid values are true, false, 'create', 'update'
  * @param string $message The message to show if the field presence validation fails.
- * @return Validator this instance
+ * @return $this
  * @deprecated 3.0.0 Will be removed in 3.0.0.
  */
 	public function validatePresence($field, $mode = true, $message = null) {
@@ -377,7 +377,7 @@ class Validator implements \ArrayAccess, \IteratorAggregate, \Countable {
  * @param bool|string|callable $when Indicates when the field is allowed to be empty
  * Valid values are true (always), 'create', 'update'. If a callable is passed then
  * the field will allowed to be empty only when the callaback returns true.
- * @return Validator this instance
+ * @return $this
  */
 	public function allowEmpty($field, $when = true) {
 		$this->field($field)->isEmptyAllowed($when);
@@ -419,7 +419,7 @@ class Validator implements \ArrayAccess, \IteratorAggregate, \Countable {
  * to be empty. Valid values are true (always), 'create', 'update'. If a
  * callable is passed then the field will allowed be empty only when
  * the callaback returns false.
- * @return Validator this instance
+ * @return $this
  */
 	public function notEmpty($field, $message = null, $when = false) {
 		if ($when === 'create' || $when === 'update') {

src/View/Helper/StringTemplateTrait.php

@@ -32,7 +32,7 @@ trait StringTemplateTrait {
  *
  * @param string|null|array $templates null or string allow reading templates. An array
  *   allows templates to be added.
- * @return void|string|array
+ * @return $this|string|array
  */
 	public function templates($templates = null) {
 		if ($templates === null || is_string($templates)) {