Docblock fixes: Backport from 4.x

src/Auth/AbstractPasswordHasher.php

@@ -21,7 +21,6 @@ use Cake\Core\InstanceConfigTrait;
  */
 abstract class AbstractPasswordHasher
 {
-
     use InstanceConfigTrait;
 
     /**
@@ -48,7 +47,7 @@ abstract class AbstractPasswordHasher
      *
      * @param string|array $password Plain text password to hash or array of data
      *   required to generate password hash.
-     * @return string Password hash
+     * @return string|false Either the password hash string or false
      */
     abstract public function hash($password);
 

src/Auth/BasicAuthenticate.php

@@ -102,7 +102,7 @@ class BasicAuthenticate extends BaseAuthenticate
      * Generate the login headers
      *
      * @param \Cake\Http\ServerRequest $request Request object.
-     * @return array Headers for logging in.
+     * @return string[] Headers for logging in.
      */
     public function loginHeaders(ServerRequest $request)
     {

src/Auth/DefaultPasswordHasher.php

@@ -41,7 +41,7 @@ class DefaultPasswordHasher extends AbstractPasswordHasher
      * Generates password hash.
      *
      * @param string $password Plain text password to hash.
-     * @return bool|string Password hash or false on failure
+     * @return string|false Password hash or false on failure
      * @link https://book.cakephp.org/3.0/en/controllers/components/authentication.html#hashing-passwords
      */
     public function hash($password)

src/Auth/DigestAuthenticate.php

@@ -213,7 +213,7 @@ class DigestAuthenticate extends BasicAuthenticate
      * Generate the login headers
      *
      * @param \Cake\Http\ServerRequest $request Request object.
-     * @return array Headers for logging in.
+     * @return string[] Headers for logging in.
      */
     public function loginHeaders(ServerRequest $request)
     {

src/Auth/FallbackPasswordHasher.php

@@ -34,7 +34,7 @@ class FallbackPasswordHasher extends AbstractPasswordHasher
     /**
      * Holds the list of password hasher objects that will be used
      *
-     * @var array
+     * @var \Cake\Auth\AbstractPasswordHasher[]
      */
     protected $_hashers = [];
 
@@ -62,7 +62,7 @@ class FallbackPasswordHasher extends AbstractPasswordHasher
      * Uses the first password hasher in the list to generate the hash
      *
      * @param string $password Plain text password to hash.
-     * @return string Password hash
+     * @return string|false Password hash
      */
     public function hash($password)
     {

src/Cache/CacheEngine.php

@@ -242,7 +242,7 @@ abstract class CacheEngine
      * Generates a safe key for use with cache engine storage engines.
      *
      * @param string $key the key passed over
-     * @return bool|string string key or false
+     * @return string|false string key or false
      */
     public function key($key)
     {
@@ -264,7 +264,7 @@ abstract class CacheEngine
      * Generates a safe key, taking account of the configured key prefix
      *
      * @param string $key the key passed over
-     * @return mixed string $key or false
+     * @return string Key
      * @throws \InvalidArgumentException If key's value is empty
      */
     protected function _key($key)

src/Cache/Engine/ApcuEngine.php

@@ -84,7 +84,7 @@ class ApcuEngine extends CacheEngine
      *
      * @param string $key Identifier for the data
      * @param int $offset How much to increment
-     * @return bool|int New incremented value, false otherwise
+     * @return int|false New incremented value, false otherwise
      * @link https://secure.php.net/manual/en/function.apcu-inc.php
      */
     public function increment($key, $offset = 1)
@@ -99,7 +99,7 @@ class ApcuEngine extends CacheEngine
      *
      * @param string $key Identifier for the data
      * @param int $offset How much to subtract
-     * @return bool|int New decremented value, false otherwise
+     * @return int|false New decremented value, false otherwise
      * @link https://secure.php.net/manual/en/function.apcu-dec.php
      */
     public function decrement($key, $offset = 1)

src/Cache/Engine/ArrayEngine.php

@@ -84,7 +84,7 @@ class ArrayEngine extends CacheEngine
      *
      * @param string $key Identifier for the data
      * @param int $offset How much to increment
-     * @return bool|int New incremented value, false otherwise
+     * @return int|false New incremented value, false otherwise
      */
     public function increment($key, $offset = 1)
     {
@@ -102,7 +102,7 @@ class ArrayEngine extends CacheEngine
      *
      * @param string $key Identifier for the data
      * @param int $offset How much to subtract
-     * @return bool|int New decremented value, false otherwise
+     * @return int|false New decremented value, false otherwise
      */
     public function decrement($key, $offset = 1)
     {

src/Cache/Engine/MemcachedEngine.php

@@ -378,7 +378,7 @@ class MemcachedEngine extends CacheEngine
      *
      * @param string $key Identifier for the data
      * @param int $offset How much to increment
-     * @return bool|int New incremented value, false otherwise
+     * @return int|false New incremented value, false otherwise
      */
     public function increment($key, $offset = 1)
     {
@@ -392,7 +392,7 @@ class MemcachedEngine extends CacheEngine
      *
      * @param string $key Identifier for the data
      * @param int $offset How much to subtract
-     * @return bool|int New decremented value, false otherwise
+     * @return int|false New decremented value, false otherwise
      */
     public function decrement($key, $offset = 1)
     {

src/Cache/Engine/RedisEngine.php

@@ -169,7 +169,7 @@ class RedisEngine extends CacheEngine
      *
      * @param string $key Identifier for the data
      * @param int $offset How much to increment
-     * @return bool|int New incremented value, false otherwise
+     * @return int|false New incremented value, false otherwise
      */
     public function increment($key, $offset = 1)
     {
@@ -189,7 +189,7 @@ class RedisEngine extends CacheEngine
      *
      * @param string $key Identifier for the data
      * @param int $offset How much to subtract
-     * @return bool|int New decremented value, false otherwise
+     * @return int|false New decremented value, false otherwise
      */
     public function decrement($key, $offset = 1)
     {

src/Cache/Engine/WincacheEngine.php

@@ -85,7 +85,7 @@ class WincacheEngine extends CacheEngine
      *
      * @param string $key Identifier for the data
      * @param int $offset How much to increment
-     * @return bool|int New incremented value, false otherwise
+     * @return int|false New incremented value, false otherwise
      */
     public function increment($key, $offset = 1)
     {
@@ -99,7 +99,7 @@ class WincacheEngine extends CacheEngine
      *
      * @param string $key Identifier for the data
      * @param int $offset How much to subtract
-     * @return bool|int New decremented value, false otherwise
+     * @return int|false New decremented value, false otherwise
      */
     public function decrement($key, $offset = 1)
     {

src/Cache/Engine/XcacheEngine.php

@@ -125,7 +125,7 @@ class XcacheEngine extends CacheEngine
      *
      * @param string $key Identifier for the data
      * @param int $offset How much to increment
-     * @return bool|int New incremented value, false otherwise
+     * @return int|false New incremented value, false otherwise
      */
     public function increment($key, $offset = 1)
     {
@@ -140,7 +140,7 @@ class XcacheEngine extends CacheEngine
      *
      * @param string $key Identifier for the data
      * @param int $offset How much to subtract
-     * @return bool|int New decremented value, false otherwise
+     * @return int|false New decremented value, false otherwise
      */
     public function decrement($key, $offset = 1)
     {

src/Collection/ExtractTrait.php

@@ -122,7 +122,7 @@ trait ExtractTrait
      * @param array $conditions A key-value list of conditions to match where the
      * key is the property path to get from the current item and the value is the
      * value to be compared the item with.
-     * @return callable
+     * @return \Closure
      */
     protected function _createMatcherFilter(array $conditions)
     {

src/Collection/Iterator/ExtractIterator.php

@@ -98,6 +98,7 @@ class ExtractIterator extends Collection
         $callback = $this->_extractor;
         $res = [];
 
+        /** @var \ArrayObject $iterator */
         foreach ($iterator->getArrayCopy() as $k => $v) {
             $res[$k] = $callback($v);
         }

src/Collection/Iterator/MapReduce.php

@@ -183,6 +183,7 @@ class MapReduce implements IteratorAggregate
             throw new LogicException('No reducer function was provided');
         }
 
+        /** @var callable $reducer */
         $reducer = $this->_reducer;
         foreach ($this->_intermediate as $key => $list) {
             $reducer($list, $key, $this);

src/Collection/Iterator/NestIterator.php

@@ -24,7 +24,6 @@ use Traversable;
  */
 class NestIterator extends Collection implements RecursiveIterator
 {
-
     /**
      * The name of the property that contains the nested items for each element
      *
@@ -48,7 +47,7 @@ class NestIterator extends Collection implements RecursiveIterator
     /**
      * Returns a traversable containing the children for the current item
      *
-     * @return \Traversable
+     * @return \RecursiveIterator
      */
     public function getChildren()
     {

src/Collection/Iterator/ZipIterator.php

@@ -50,7 +50,7 @@ class ZipIterator extends MultipleIterator implements CollectionInterface, Seria
     /**
      * The function to use for zipping items together
      *
-     * @var callable
+     * @var callable|null
      */
     protected $_callback;
 
@@ -87,7 +87,7 @@ class ZipIterator extends MultipleIterator implements CollectionInterface, Seria
      * Returns the value resulting out of zipping all the elements for all the
      * iterators with the same positional index.
      *
-     * @return mixed
+     * @return array|false
      */
     public function current()
     {

src/Console/ConsoleInputArgument.php

@@ -50,7 +50,7 @@ class ConsoleInputArgument
     /**
      * An array of valid choices for this argument.
      *
-     * @var array
+     * @var string[]
      */
     protected $_choices;
 
@@ -60,7 +60,7 @@ class ConsoleInputArgument
      * @param string|array $name The long name of the option, or an array with all the properties.
      * @param string $help The help text for this option
      * @param bool $required Whether this argument is required. Missing required args will trigger exceptions
-     * @param array $choices Valid choices for this option.
+     * @param string[] $choices Valid choices for this option.
      */
     public function __construct($name, $help = '', $required = false, $choices = [])
     {
@@ -153,7 +153,7 @@ class ConsoleInputArgument
      * Check that $value is a valid choice for this argument.
      *
      * @param string $value The choice to validate.
-     * @return bool
+     * @return true
      * @throws \Cake\Console\Exception\ConsoleException
      */
     public function validChoice($value)
@@ -161,7 +161,7 @@ class ConsoleInputArgument
         if (empty($this->_choices)) {
             return true;
         }
-        if (!in_array($value, $this->_choices)) {
+        if (!in_array($value, $this->_choices, true)) {
             throw new ConsoleException(
                 sprintf(
                     '"%s" is not a valid value for %s. Please use one of "%s"',

src/Console/ConsoleInputOption.php

@@ -57,7 +57,7 @@ class ConsoleInputOption
     /**
      * Default value for the option
      *
-     * @var mixed
+     * @var string|bool
      */
     protected $_default;
 
@@ -71,7 +71,7 @@ class ConsoleInputOption
     /**
      * An array of choices for the option.
      *
-     * @var array
+     * @var string[]
      */
     protected $_choices;
 
@@ -82,7 +82,7 @@ class ConsoleInputOption
      * @param string $short The short alias for this option
      * @param string $help The help text for this option
      * @param bool $boolean Whether this option is a boolean option. Boolean options don't consume extra tokens
-     * @param string $default The default value for this option.
+     * @param string|bool $default The default value for this option.
      * @param string[] $choices Valid choices for this option.
      * @param bool $multiple Whether this option can accept multiple value definition.
      * @throws \Cake\Console\Exception\ConsoleException
@@ -214,8 +214,8 @@ class ConsoleInputOption
     /**
      * Check that a value is a valid choice for this option.
      *
-     * @param string $value The choice to validate.
-     * @return bool
+     * @param string|bool $value The choice to validate.
+     * @return true
      * @throws \Cake\Console\Exception\ConsoleException
      */
     public function validChoice($value)
@@ -223,7 +223,7 @@ class ConsoleInputOption
         if (empty($this->_choices)) {
             return true;
         }
-        if (!in_array($value, $this->_choices)) {
+        if (!in_array($value, $this->_choices, true)) {
             throw new ConsoleException(
                 sprintf(
                     '"%s" is not a valid value for --%s. Please use one of "%s"',

src/Console/ConsoleOutput.php

@@ -82,8 +82,9 @@ class ConsoleOutput
     protected $_output;
 
     /**
-     * The current output type. Manipulated with ConsoleOutput::outputAs();
+     * The current output type.
      *
+     * @see setOutputAs() For manipulation.
      * @var int
      */
     protected $_outputAs = self::COLOR;

src/Controller/Controller.php

@@ -147,7 +147,7 @@ class Controller implements EventListenerInterface, EventDispatcherInterface
      *
      * @var string
      */
-    protected $_responseClass = 'Cake\Http\Response';
+    protected $_responseClass = Response::class;
 
     /**
      * Settings for pagination.

src/Routing/RouteCollection.php

@@ -222,7 +222,7 @@ class RouteCollection
      * and newer style urls containing '_name'
      *
      * @param array $url The url to match.
-     * @return array The set of names of the url
+     * @return string[] The set of names of the url
      */
     protected function _getNames($url)
     {
@@ -370,11 +370,11 @@ class RouteCollection
     /**
      * Get/set the extensions that the route collection could handle.
      *
-     * @param null|string|array $extensions Either the list of extensions to set,
+     * @param null|string|string[] $extensions Either the list of extensions to set,
      *   or null to get.
      * @param bool $merge Whether to merge with or override existing extensions.
      *   Defaults to `true`.
-     * @return array The valid extensions.
+     * @return string[] The valid extensions.
      * @deprecated 3.5.0 Use getExtensions()/setExtensions() instead.
      */
     public function extensions($extensions = null, $merge = true)
@@ -445,6 +445,7 @@ class RouteCollection
      * @param string $name Name of the middleware group
      * @param string[] $middlewareNames Names of the middleware
      * @return $this
+     * @throws \RuntimeException
      */
     public function middlewareGroup($name, array $middlewareNames)
     {

src/Shell/Helper/ProgressHelper.php

@@ -37,7 +37,7 @@ class ProgressHelper extends Helper
     /**
      * The current progress.
      *
-     * @var int
+     * @var int|float
      */
     protected $_progress = 0;
 
@@ -112,7 +112,7 @@ class ProgressHelper extends Helper
     /**
      * Increment the progress bar.
      *
-     * @param int $num The amount of progress to advance by.
+     * @param int|float $num The amount of progress to advance by.
      * @return $this
      */
     public function increment($num = 1)

src/Shell/Helper/TableHelper.php

@@ -21,7 +21,6 @@ use Cake\Console\Helper;
  */
 class TableHelper extends Helper
 {
-
     /**
      * Default config for this helper.
      *
@@ -37,7 +36,7 @@ class TableHelper extends Helper
      * Calculate the column widths
      *
      * @param array $rows The rows on which the columns width will be calculated on.
-     * @return array
+     * @return int[]
      */
     protected function _calculateWidths($rows)
     {
@@ -77,7 +76,7 @@ class TableHelper extends Helper
     /**
      * Output a row separator.
      *
-     * @param array $widths The widths of each column to output.
+     * @param int[] $widths The widths of each column to output.
      * @return void
      */
     protected function _rowSeparator($widths)
@@ -94,7 +93,7 @@ class TableHelper extends Helper
      * Output a row.
      *
      * @param array $row The row to output.
-     * @param array $widths The widths of each column to output.
+     * @param int[] $widths The widths of each column to output.
      * @param array $options Options to be passed.
      * @return void
      */

src/Utility/Security.php

@@ -57,6 +57,7 @@ class Security
      * @param mixed $salt If true, automatically prepends the application's salt
      *   value to $string (Security.salt).
      * @return string Hash
+     * @throws \RuntimeException
      * @link https://book.cakephp.org/3.0/en/core-libraries/security.html#hashing-data
      */
     public static function hash($string, $algorithm = null, $salt = false)