Fix up doc blocks and issues around mixed return type.

src/Auth/BaseAuthenticate.php

@@ -202,7 +202,7 @@ abstract class BaseAuthenticate implements EventListenerInterface
      *
      * @param \Cake\Http\ServerRequest $request Request to get authentication information from.
      * @param \Cake\Http\Response $response A response object that can have headers added.
-     * @return mixed Either false on failure, or an array of user data on success.
+     * @return array|false Either false on failure, or an array of user data on success.
      */
     abstract public function authenticate(ServerRequest $request, Response $response);
 
@@ -211,7 +211,7 @@ abstract class BaseAuthenticate implements EventListenerInterface
      * systems like basic and digest auth.
      *
      * @param \Cake\Http\ServerRequest $request Request object.
-     * @return mixed Either false or an array of user information
+     * @return array|false Either false or an array of user information
      */
     public function getUser(ServerRequest $request)
     {

src/Auth/BasicAuthenticate.php

@@ -59,7 +59,7 @@ class BasicAuthenticate extends BaseAuthenticate
      *
      * @param \Cake\Http\ServerRequest $request The request to authenticate with.
      * @param \Cake\Http\Response $response The response to add headers to.
-     * @return mixed Either false on failure, or an array of user data on success.
+     * @return array|false Either false on failure, or an array of user data on success.
      */
     public function authenticate(ServerRequest $request, Response $response)
     {
@@ -70,7 +70,7 @@ class BasicAuthenticate extends BaseAuthenticate
      * Get a user based on information in the request. Used by cookie-less auth for stateless clients.
      *
      * @param \Cake\Http\ServerRequest $request Request object.
-     * @return mixed Either false or an array of user information
+     * @return array|false Either false or an array of user information
      */
     public function getUser(ServerRequest $request)
     {

src/Auth/DigestAuthenticate.php

@@ -101,7 +101,7 @@ class DigestAuthenticate extends BasicAuthenticate
      * Get a user based on information in the request. Used by cookie-less auth for stateless clients.
      *
      * @param \Cake\Http\ServerRequest $request Request object.
-     * @return mixed Either false or an array of user information
+     * @return array|false Either false or an array of user information
      */
     public function getUser(ServerRequest $request)
     {

src/Auth/FormAuthenticate.php

@@ -74,7 +74,7 @@ class FormAuthenticate extends BaseAuthenticate
      *
      * @param \Cake\Http\ServerRequest $request The request that contains login information.
      * @param \Cake\Http\Response $response Unused response object.
-     * @return mixed False on login failure. An array of User data on success.
+     * @return array|false False on login failure. An array of User data on success.
      */
     public function authenticate(ServerRequest $request, Response $response)
     {

src/Auth/Storage/MemoryStorage.php

@@ -29,9 +29,9 @@ class MemoryStorage implements StorageInterface
     protected $_user;
 
     /**
-     * Redirect url.
+     * Redirect URL.
      *
-     * @var string|null
+     * @var string|array|null
      */
     protected $_redirectUrl;
 

src/Auth/Storage/StorageInterface.php

@@ -51,7 +51,7 @@ interface StorageInterface
      *
      * @param mixed $url Redirect URL. If `null` returns current URL. If `false`
      *   deletes currently set URL.
-     * @return mixed
+     * @return string|array|null
      */
     public function redirectUrl($url = null);
 }

src/Cache/Cache.php

@@ -362,9 +362,9 @@ class Cache
      * @param string $key Identifier for the data
      * @param int $offset How much to add
      * @param string $config Optional string configuration name. Defaults to 'default'
-     * @return mixed new value, or false if the data doesn't exist, is not integer,
+     * @return int|false New value, or false if the data doesn't exist, is not integer,
      *    or if there was an error fetching it.
-     * @throws \Cake\Cache\InvalidArgumentException when offset < 0
+     * @throws \Cake\Cache\InvalidArgumentException When offset < 0
      */
     public static function increment(string $key, int $offset = 1, string $config = 'default')
     {
@@ -381,7 +381,7 @@ class Cache
      * @param string $key Identifier for the data
      * @param int $offset How much to subtract
      * @param string $config Optional string configuration name. Defaults to 'default'
-     * @return mixed new value, or false if the data doesn't exist, is not integer,
+     * @return int|false New value, or false if the data doesn't exist, is not integer,
      *   or if there was an error fetching it
      * @throws \Cake\Cache\InvalidArgumentException when offset < 0
      */

src/Console/ConsoleIo.php

@@ -363,9 +363,9 @@ class ConsoleIo
      *
      * @param string $prompt Prompt text.
      * @param string|null $default Default input value.
-     * @return mixed Either the default value, or the user-provided input.
+     * @return string Either the default value, or the user-provided input.
      */
-    public function ask(string $prompt, ?string $default = null)
+    public function ask(string $prompt, ?string $default = null): string
     {
         return $this->_getInput($prompt, null, $default);
     }
@@ -388,7 +388,7 @@ class ConsoleIo
      * @param string|null $style The style to get or create.
      * @param array|bool|null $definition The array definition of the style to change or create a style
      *   or false to remove a style.
-     * @return mixed If you are getting styles, the style or null will be returned. If you are creating/modifying
+     * @return array|null|true If you are getting styles, the style or null will be returned. If you are creating/modifying
      *   styles true will be returned.
      * @see \Cake\Console\ConsoleOutput::styles()
      */
@@ -403,9 +403,9 @@ class ConsoleIo
      * @param string $prompt Prompt text.
      * @param string|array $options Array or string of options.
      * @param string|null $default Default input value.
-     * @return mixed Either the default value, or the user-provided input.
+     * @return string Either the default value, or the user-provided input.
      */
-    public function askChoice(string $prompt, $options, ?string $default = null)
+    public function askChoice(string $prompt, $options, ?string $default = null): string
     {
         if ($options && is_string($options)) {
             if (strpos($options, ',')) {

src/Console/ConsoleOutput.php

@@ -282,9 +282,9 @@ class ConsoleOutput
      * ```
      *
      * @param string|null $style The style to get or create.
-     * @param array|bool|null $definition The array definition of the style to change or create a style
+     * @param array|false|null $definition The array definition of the style to change or create a style
      *   or false to remove a style.
-     * @return mixed If you are getting styles, the style or null will be returned. If you are creating/modifying
+     * @return array|true|null If you are getting styles, the style or null will be returned. If you are creating/modifying
      *   styles true will be returned.
      */
     public function styles(?string $style = null, $definition = null)

src/Console/Shell.php

@@ -626,7 +626,7 @@ class Shell
      * @return mixed Either the default value, or the user-provided input.
      * @link https://book.cakephp.org/3.0/en/console-and-shells.html#Shell::in
      */
-    public function in(string $prompt, $options = null, $default = null)
+    public function in(string $prompt, $options = null, ?string $default = null): ?string
     {
         if (!$this->interactive) {
             return $default;
@@ -666,7 +666,7 @@ class Shell
      * @param int $newlines Number of newlines to append
      * @return int|null The number of bytes returned from writing to stdout.
      */
-    public function verbose($message, int $newlines = 1)
+    public function verbose($message, int $newlines = 1): ?int
     {
         return $this->_io->verbose($message, $newlines);
     }
@@ -678,7 +678,7 @@ class Shell
      * @param int $newlines Number of newlines to append
      * @return int|null The number of bytes returned from writing to stdout.
      */
-    public function quiet($message, int $newlines = 1)
+    public function quiet($message, int $newlines = 1): ?int
     {
         return $this->_io->quiet($message, $newlines);
     }
@@ -700,7 +700,7 @@ class Shell
      * @return int|null The number of bytes returned from writing to stdout.
      * @link https://book.cakephp.org/3.0/en/console-and-shells.html#Shell::out
      */
-    public function out($message = null, int $newlines = 1, int $level = Shell::NORMAL)
+    public function out($message = null, int $newlines = 1, int $level = Shell::NORMAL): ?int
     {
         return $this->_io->out($message, $newlines, $level);
     }
@@ -754,7 +754,7 @@ class Shell
      * @return int|null The number of bytes returned from writing to stdout.
      * @see https://book.cakephp.org/3.0/en/console-and-shells.html#Shell::out
      */
-    public function success($message = null, int $newlines = 1, int $level = Shell::NORMAL)
+    public function success($message = null, int $newlines = 1, int $level = Shell::NORMAL): ?int
     {
         return $this->_io->success($message, $newlines, $level);
     }
@@ -809,12 +809,14 @@ class Shell
      */
     public function clear(): void
     {
-        if (empty($this->params['noclear'])) {
-            if (DIRECTORY_SEPARATOR === '/') {
-                passthru('clear');
-            } else {
-                passthru('cls');
-            }
+        if (!empty($this->params['noclear'])) {
+            return;
+        }
+
+        if (DIRECTORY_SEPARATOR === '/') {
+            passthru('clear');
+        } else {
+            passthru('cls');
         }
     }
 

src/Controller/Component.php

@@ -139,7 +139,7 @@ class Component implements EventListenerInterface
      * Magic method for lazy loading $components.
      *
      * @param string $name Name of component to get.
-     * @return mixed A Component object or null.
+     * @return \Cake\Controller\Component|null A Component object or null.
      */
     public function __get(string $name)
     {

src/Database/DriverInterface.php

@@ -40,14 +40,14 @@ interface DriverInterface
     /**
      * Returns correct connection resource or object that is internally used.
      *
-     * @return mixed Connection object used internally.
+     * @return object Connection object used internally.
      */
     public function getConnection();
 
     /**
      * Set the internal connection object.
      *
-     * @param mixed $connection The connection instance.
+     * @param object $connection The connection instance.
      * @return $this
      */
     public function setConnection($connection);

src/Database/Statement/StatementDecorator.php

@@ -216,7 +216,7 @@ class StatementDecorator implements StatementInterface, Countable, IteratorAggre
      * Returns the value of the result at position.
      *
      * @param int $position The numeric position of the column to retrieve in the result
-     * @return mixed|false Returns the specific value of the column designated at $position
+     * @return mixed Returns the specific value of the column designated at $position
      */
     public function fetchColumn(int $position)
     {

src/Database/StatementInterface.php

@@ -156,7 +156,7 @@ interface StatementInterface
      * Returns the value of the result at position.
      *
      * @param int $position The numeric position of the column to retrieve in the result
-     * @return mixed|false Returns the specific value of the column designated at $position
+     * @return mixed Returns the specific value of the column designated at $position
      */
     public function fetchColumn(int $position);
 

src/Database/Type/BinaryUuidType.php

@@ -132,11 +132,11 @@ class BinaryUuidType extends BaseType
      * Converts a string uuid to a binary representation
      *
      *
-     * @param mixed $string The value to convert.
+     * @param string $string The value to convert.
      *
-     * @return mixed Converted value.
+     * @return string Converted value.
      */
-    protected function convertStringToBinaryUuid($string)
+    protected function convertStringToBinaryUuid($string): string
     {
         $string = str_replace('-', '', $string);
 

src/Datasource/EntityTrait.php

@@ -1067,7 +1067,7 @@ trait EntityTrait
      * Get a single value of an invalid field. Returns null if not set.
      *
      * @param string $field The name of the field.
-     * @return mixed
+     * @return mixed|null
      */
     public function getInvalidField(string $field)
     {

src/Datasource/InvalidPropertyInterface.php

@@ -46,7 +46,7 @@ interface InvalidPropertyInterface
      * Get a single value of an invalid field. Returns null if not set.
      *
      * @param string $field The name of the field.
-     * @return mixed
+     * @return mixed|null
      */
     public function getInvalidField(string $field);
 

src/Datasource/QueryCacher.php

@@ -69,7 +69,7 @@ class QueryCacher
      * Load the cached results from the cache or run the query.
      *
      * @param object $query The query the cache read is for.
-     * @return mixed Either the cached results or null.
+     * @return mixed|null Either the cached results or null.
      */
     public function fetch(object $query)
     {

src/Error/Debugger.php

@@ -261,7 +261,7 @@ class Debugger
      * - `start` - The stack frame to start generating a trace from. Defaults to 0
      *
      * @param array $options Format for outputting stack trace.
-     * @return mixed Formatted stack trace.
+     * @return string|array Formatted stack trace.
      * @link https://book.cakephp.org/3.0/en/development/debugging.html#generating-stack-traces
      */
     public static function trace(array $options = [])
@@ -283,7 +283,7 @@ class Debugger
      *
      * @param array|\Exception $backtrace Trace as array or an exception object.
      * @param array $options Format for outputting stack trace.
-     * @return mixed Formatted stack trace.
+     * @return string|array Formatted stack trace.
      * @link https://book.cakephp.org/3.0/en/development/debugging.html#generating-stack-traces
      */
     public static function formatTrace($backtrace, array $options = [])

src/Http/Client.php

@@ -591,6 +591,7 @@ class Client implements ClientInterface
     protected function _addAuthentication(Request $request, array $options): Request
     {
         $auth = $options['auth'];
+        /** @var \Cake\Http\Client\Auth\Basic $adapter */
         $adapter = $this->_createAuth($auth, $options);
         $result = $adapter->authentication($request, $options['auth']);
 
@@ -610,6 +611,7 @@ class Client implements ClientInterface
     protected function _addProxy(Request $request, array $options): Request
     {
         $auth = $options['proxy'];
+        /** @var \Cake\Http\Client\Auth\Basic $adapter */
         $adapter = $this->_createAuth($auth, $options);
         $result = $adapter->proxyAuthentication($request, $options['proxy']);
 
@@ -624,7 +626,7 @@ class Client implements ClientInterface
      *
      * @param array $auth The authentication options to use.
      * @param array $options The overall request options to use.
-     * @return mixed Authentication strategy instance.
+     * @return object Authentication strategy instance.
      * @throws \Cake\Core\Exception\Exception when an invalid strategy is chosen.
      */
     protected function _createAuth(array $auth, array $options)

src/Http/Response.php

@@ -710,7 +710,7 @@ class Response implements ResponseInterface
      * e.g `getMimeType('pdf'); // returns 'application/pdf'`
      *
      * @param string $alias the content type alias to map
-     * @return mixed String mapped mime type or false if $alias is not mapped
+     * @return string|array|false String mapped mime type or false if $alias is not mapped
      */
     public function getMimeType(string $alias)
     {

src/basics.php

@@ -78,7 +78,7 @@ if (!function_exists('stackTrace')) {
      * - `start` - The stack frame to start generating a trace from. Defaults to 1
      *
      * @param array $options Format for outputting stack trace
-     * @return mixed Formatted stack trace
+     * @return string|array Formatted stack trace
      */
     function stackTrace(array $options = [])
     {

tests/test_app/TestApp/Shell/TestingDispatchShell.php

@@ -31,9 +31,11 @@ class TestingDispatchShell extends Shell
         $this->out('<info>Welcome to CakePHP Console</info>');
     }
 
-    public function out($message = null, int $newlines = 1, int $level = Shell::NORMAL)
+    public function out($message = null, int $newlines = 1, int $level = Shell::NORMAL): ?int
     {
         echo $message . "\n";
+
+        return 1;
     }
 
     public function testTask()