Merge pull request #7527 from dereuromark/master-fix-doc-blocks

Do not mix void with other return types.

src/Console/ConsoleOutput.php

@@ -301,7 +301,7 @@ class ConsoleOutput
      * Get/Set the output type to use. The output type how formatting tags are treated.
      *
      * @param int|null $type The output type to use. Should be one of the class constants.
-     * @return int|void  Either null or the value if getting.
+     * @return int|null  Either null or the value if getting.
      */
     public function outputAs($type = null)
     {

src/Controller/Component/AuthComponent.php

@@ -251,7 +251,7 @@ class AuthComponent extends Component
      * Callback for Controller.startup event.
      *
      * @param \Cake\Event\Event $event Event instance.
-     * @return void|\Cake\Network\Response
+     * @return \Cake\Network\Response|null
      */
     public function startup(Event $event)
     {
@@ -266,32 +266,32 @@ class AuthComponent extends Component
      * `checkAuthIn` config.
      *
      * @param \Cake\Event\Event $event Event instance.
-     * @return void|\Cake\Network\Response
+     * @return \Cake\Network\Response|null
      */
     public function authCheck(Event $event)
     {
         if ($this->_config['checkAuthIn'] !== $event->name()) {
-            return;
+            return null;
         }
 
         $controller = $event->subject();
 
         $action = strtolower($controller->request->params['action']);
         if (!$controller->isAction($action)) {
-            return;
+            return null;
         }
 
         $this->_setDefaults();
 
         if ($this->_isAllowed($controller)) {
-            return;
+            return null;
         }
 
         $isLoginAction = $this->_isLoginAction($controller);
 
         if (!$this->_getUser()) {
             if ($isLoginAction) {
-                return;
+                return null;
             }
             $result = $this->_unauthenticated($controller);
             if ($result instanceof Response) {
@@ -304,7 +304,7 @@ class AuthComponent extends Component
             empty($this->_config['authorize']) ||
             $this->isAuthorized($this->user())
         ) {
-            return;
+            return null;
         }
 
         $event->stopPropagation();
@@ -347,7 +347,7 @@ class AuthComponent extends Component
      * is returned.
      *
      * @param \Cake\Controller\Controller $controller A reference to the controller object.
-     * @return void|\Cake\Network\Response Null if current action is login action
+     * @return \Cake\Network\Response|null Null if current action is login action
      *   else response object returned by authenticate object or Controller::redirect().
      */
     protected function _unauthenticated(Controller $controller)
@@ -657,14 +657,14 @@ class AuthComponent extends Component
      * Get the current user from storage.
      *
      * @param string $key Field to retrieve. Leave null to get entire User record.
-     * @return array|void Either User record or null if no user is logged in.
+     * @return array|null Either User record or null if no user is logged in.
      * @link http://book.cakephp.org/3.0/en/controllers/components/authentication.html#accessing-the-logged-in-user
      */
     public function user($key = null)
     {
         $user = $this->storage()->read();
         if (!$user) {
-            return;
+            return null;
         }
 
         if ($key === null) {
@@ -818,13 +818,13 @@ class AuthComponent extends Component
      *
      * @param \Cake\Auth\Storage\StorageInterface|null $storage Sets provided
      *   object as storage or if null returns configuread storage object.
-     * @return \Cake\Auth\Storage\StorageInterface|void
+     * @return \Cake\Auth\Storage\StorageInterface|null
      */
     public function storage(StorageInterface $storage = null)
     {
         if ($storage !== null) {
             $this->_storage = $storage;
-            return;
+            return null;
         }
 
         if ($this->_storage) {

src/Controller/Component/RequestHandlerComponent.php

@@ -245,16 +245,16 @@ class RequestHandlerComponent extends Component
      * @param Event $event The Controller.beforeRedirect event.
      * @param string|array $url A string or array containing the redirect location
      * @param \Cake\Network\Response $response The response object.
-     * @return void|\Cake\Network\Response The response object if the redirect is caught.
+     * @return \Cake\Network\Response|null The response object if the redirect is caught.
      */
     public function beforeRedirect(Event $event, $url, Response $response)
     {
         $request = $this->request;
         if (!$request->is('ajax')) {
-            return;
+            return null;
         }
         if (empty($url)) {
-            return;
+            return null;
         }
         if (is_array($url)) {
             $url = Router::url($url + ['_base' => false]);

src/Controller/Controller.php

@@ -484,7 +484,7 @@ class Controller implements EventListenerInterface, EventDispatcherInterface
      * - Calls the controller `beforeFilter`.
      * - triggers Component `startup` methods.
      *
-     * @return void|\Cake\Network\Response
+     * @return \Cake\Network\Response|null
      */
     public function startupProcess()
     {
@@ -505,7 +505,7 @@ class Controller implements EventListenerInterface, EventDispatcherInterface
      * - triggers the component `shutdown` callback.
      * - calls the Controller's `afterFilter` method.
      *
-     * @return void|\Cake\Network\Response
+     * @return \Cake\Network\Response|null
      */
     public function shutdownProcess()
     {
@@ -522,7 +522,7 @@ class Controller implements EventListenerInterface, EventDispatcherInterface
      * @param string|array $url A string or array-based URL pointing to another location within the app,
      *     or an absolute URL
      * @param int $status HTTP status code (eg: 301)
-     * @return void|\Cake\Network\Response
+     * @return \Cake\Network\Response|null
      * @link http://book.cakephp.org/3.0/en/controllers.html#Controller::redirect
      */
     public function redirect($url, $status = 302)

src/Database/Query.php

@@ -1580,7 +1580,7 @@ class Query implements ExpressionInterface, IteratorAggregate
      *
      * @param callable $callback the function to be executed for each ExpressionInterface
      *   found inside this query.
-     * @return void|$this
+     * @return $this|null
      */
     public function traverseExpressions(callable $callback)
     {
@@ -1589,7 +1589,7 @@ class Query implements ExpressionInterface, IteratorAggregate
                 foreach ($expression as $e) {
                     $visitor($e);
                 }
-                return;
+                return null;
             }
 
             if ($expression instanceof ExpressionInterface) {

src/I18n/I18n.php

@@ -120,7 +120,7 @@ class I18n
      * @param string|null $locale The locale for the translator.
      * @param callable|null $loader A callback function or callable class responsible for
      * constructing a translations package instance.
-     * @return \Aura\Intl\Translator|void The configured translator.
+     * @return \Aura\Intl\Translator|null The configured translator.
      */
     public static function translator($name = 'default', $locale = null, callable $loader = null)
     {
@@ -131,7 +131,7 @@ class I18n
 
             $packages = static::translators()->getPackages();
             $packages->set($name, $locale, $loader);
-            return;
+            return null;
         }
 
         $translators = static::translators();
@@ -206,7 +206,7 @@ class I18n
      * locale as stored in the `intl.default_locale` PHP setting.
      *
      * @param string|null $locale The name of the locale to set as default.
-     * @return string|void The name of the default locale.
+     * @return string|null The name of the default locale.
      */
     public static function locale($locale = null)
     {
@@ -217,7 +217,7 @@ class I18n
             if (isset(static::$_collection)) {
                 static::translators()->setLocale($locale);
             }
-            return;
+            return null;
         }
 
         $current = Locale::getDefault();

src/I18n/functions.php

@@ -69,13 +69,13 @@ if (!function_exists('__d')) {
      * @param string $domain Domain.
      * @param string $msg String to translate.
      * @param mixed $args Array with arguments or multiple arguments in function.
-     * @return void|string Translated string.
+     * @return string|null Translated string.
      * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__d
      */
     function __d($domain, $msg, $args = null)
     {
         if (!$msg) {
-            return;
+            return null;
         }
         $arguments = func_num_args() === 3 ? (array)$args : array_slice(func_get_args(), 2);
         return I18n::translator($domain)->translate($msg, $arguments);
@@ -94,13 +94,13 @@ if (!function_exists('__dn')) {
      * @param string $plural Plural.
      * @param int $count Count.
      * @param mixed $args Array with arguments or multiple arguments in function.
-     * @return void|string Plural form of translated string.
+     * @return string|null Plural form of translated string.
      * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__dn
      */
     function __dn($domain, $singular, $plural, $count, $args = null)
     {
         if (!$singular) {
-            return;
+            return null;
         }
 
         $arguments = func_num_args() === 5 ? (array)$args : array_slice(func_get_args(), 4);
@@ -121,13 +121,13 @@ if (!function_exists('__x')) {
      * @param string $context Context of the text.
      * @param string $singular Text to translate.
      * @param mixed $args Array with arguments or multiple arguments in function.
-     * @return void|string Translated string.
+     * @return string|null Translated string.
      * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__
      */
     function __x($context, $singular, $args = null)
     {
         if (!$singular) {
-            return;
+            return null;
         }
 
         $arguments = func_num_args() === 3 ? (array)$args : array_slice(func_get_args(), 2);
@@ -148,13 +148,13 @@ if (!function_exists('__xn')) {
      * @param string $plural Plural text.
      * @param int $count Count.
      * @param mixed $args Array with arguments or multiple arguments in function.
-     * @return void|string Plural form of translated string.
+     * @return string|null Plural form of translated string.
      * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__xn
      */
     function __xn($context, $singular, $plural, $count, $args = null)
     {
         if (!$singular) {
-            return;
+            return null;
         }
 
         $arguments = func_num_args() === 5 ? (array)$args : array_slice(func_get_args(), 2);
@@ -176,13 +176,13 @@ if (!function_exists('__dx')) {
      * @param string $context Context of the text.
      * @param string $msg String to translate.
      * @param mixed $args Array with arguments or multiple arguments in function.
-     * @return void|string Translated string.
+     * @return string|null Translated string.
      * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__dx
      */
     function __dx($domain, $context, $msg, $args = null)
     {
         if (!$msg) {
-            return;
+            return null;
         }
 
         $arguments = func_num_args() === 4 ? (array)$args : array_slice(func_get_args(), 2);
@@ -207,13 +207,13 @@ if (!function_exists('__dxn')) {
      * @param string $plural Plural text.
      * @param int $count Count.
      * @param mixed $args Array with arguments or multiple arguments in function.
-     * @return void|string Plural form of translated string.
+     * @return string|null Plural form of translated string.
      * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__dxn
      */
     function __dxn($domain, $context, $singular, $plural, $count, $args = null)
     {
         if (!$singular) {
-            return;
+            return null;
         }
 
         $arguments = func_num_args() === 6 ? (array)$args : array_slice(func_get_args(), 2);

src/Routing/Dispatcher.php

@@ -54,7 +54,7 @@ class Dispatcher
      *
      * @param \Cake\Network\Request $request Request object to dispatch.
      * @param \Cake\Network\Response $response Response object to put the results of the dispatch into.
-     * @return string|void if `$request['return']` is set then it returns response body, null otherwise
+     * @return string|null if `$request['return']` is set then it returns response body, null otherwise
      * @throws \Cake\Routing\Exception\MissingControllerException When the controller is missing.
      */
     public function dispatch(Request $request, Response $response)
@@ -67,7 +67,7 @@ class Dispatcher
                 return $beforeEvent->result->body();
             }
             $beforeEvent->result->send();
-            return;
+            return null;
         }
 
         $controller = false;

src/Routing/Route/Route.php

@@ -116,7 +116,7 @@ class Route
      * Get/Set the supported extensions for this route.
      *
      * @param null|string|array $extensions The extensions to set. Use null to get.
-     * @return array|void The extensions or null.
+     * @return array|null The extensions or null.
      */
     public function extensions($extensions = null)
     {

src/Routing/RouteBuilder.php

@@ -132,7 +132,7 @@ class RouteBuilder
      * Get or set default route class.
      *
      * @param string|null $routeClass Class name.
-     * @return string|void
+     * @return string|null
      */
     public function routeClass($routeClass = null)
     {
@@ -149,7 +149,7 @@ class RouteBuilder
      * extensions applied. However, setting extensions does not modify existing routes.
      *
      * @param null|string|array $extensions Either the extensions to use or null.
-     * @return array|void
+     * @return array|null
      */
     public function extensions($extensions = null)
     {

src/Routing/Router.php

@@ -161,7 +161,7 @@ class Router
      * Get or set default route class.
      *
      * @param string|null $routeClass Class name.
-     * @return string|void
+     * @return string|null
      */
     public static function defaultRouteClass($routeClass = null)
     {

src/Shell/CompletionShell.php

@@ -51,7 +51,7 @@ class CompletionShell extends Shell
     /**
      * list commands
      *
-     * @return void|int|bool Returns the number of bytes returned from writing to stdout.
+     * @return int|bool|null Returns the number of bytes returned from writing to stdout.
      */
     public function commands()
     {
@@ -62,7 +62,7 @@ class CompletionShell extends Shell
     /**
      * list options for the named command
      *
-     * @return void|int|bool Returns the number of bytes returned from writing to stdout.
+     * @return int|bool|null Returns the number of bytes returned from writing to stdout.
      */
     public function options()
     {
@@ -78,7 +78,7 @@ class CompletionShell extends Shell
     /**
      * list subcommands for the named command
      *
-     * @return void|int|bool Returns the number of bytes returned from writing to stdout.
+     * @return int|bool|null Returns the number of bytes returned from writing to stdout.
      */
     public function subcommands()
     {
@@ -93,7 +93,7 @@ class CompletionShell extends Shell
     /**
      * Guess autocomplete from the whole argument string
      *
-     * @return void|int|bool Returns the number of bytes returned from writing to stdout.
+     * @return int|bool|null Returns the number of bytes returned from writing to stdout.
      */
     public function fuzzy()
     {
@@ -151,7 +151,7 @@ class CompletionShell extends Shell
      * Emit results as a string, space delimited
      *
      * @param array $options The options to output
-     * @return void|int|bool Returns the number of bytes returned from writing to stdout.
+     * @return int|bool|null Returns the number of bytes returned from writing to stdout.
      */
     protected function _output($options = [])
     {

src/Shell/I18nShell.php

@@ -74,7 +74,7 @@ class I18nShell extends Shell
      * Inits PO file from POT file.
      *
      * @param string|null $language Language code to use.
-     * @return void|int
+     * @return int|null
      */
     public function init($language = null)
     {

src/TestSuite/Fixture/TestFixture.php

@@ -204,13 +204,13 @@ class TestFixture implements FixtureInterface
      * Get/Set the Cake\Database\Schema\Table instance used by this fixture.
      *
      * @param \Cake\Database\Schema\Table $schema The table to set.
-     * @return void|\Cake\Database\Schema\Table
+     * @return \Cake\Database\Schema\Table|null
      */
     public function schema(Table $schema = null)
     {
         if ($schema) {
             $this->_schema = $schema;
-            return;
+            return null;
         }
         return $this->_schema;
     }

src/Utility/Hash.php

@@ -510,7 +510,7 @@ class Hash
      * @param array $data Source array from which to extract the data
      * @param array $paths An array containing one or more Hash::extract()-style key paths
      * @param string $format Format string into which values will be inserted, see sprintf()
-     * @return void|array An array of strings extracted from `$path` and formatted with `$format`
+     * @return array|null An array of strings extracted from `$path` and formatted with `$format`
      * @link http://book.cakephp.org/3.0/en/core-libraries/hash.html#Hash::format
      * @see sprintf()
      * @see Hash::extract()
@@ -521,7 +521,7 @@ class Hash
         $count = count($paths);
 
         if (!$count) {
-            return;
+            return null;
         }
 
         for ($i = 0; $i < $count; $i++) {
@@ -549,7 +549,7 @@ class Hash
      *
      * @param array $data The data to search through.
      * @param array $needle The values to file in $data
-     * @return bool true if $data contains $needle, false otherwise
+     * @return bool true If $data contains $needle, false otherwise
      * @link http://book.cakephp.org/3.0/en/core-libraries/hash.html#Hash::contains
      */
     public static function contains(array $data, array $needle)

src/View/Helper.php

@@ -142,7 +142,7 @@ class Helper implements EventListenerInterface
      * Lazy loads helpers.
      *
      * @param string $name Name of the property being accessed.
-     * @return \Cake\View\Helper|void Helper instance if helper with provided name exists
+     * @return \Cake\View\Helper|null Helper instance if helper with provided name exists
      */
     public function __get($name)
     {

src/View/Helper/FlashHelper.php

@@ -64,14 +64,14 @@ class FlashHelper extends Helper
      * @param string $key The [Flash.]key you are rendering in the view.
      * @param array $options Additional options to use for the creation of this flash message.
      *    Supports the 'params', and 'element' keys that are used in the helper.
-     * @return string|void Rendered flash message or null if flash key does not exist
+     * @return string|null Rendered flash message or null if flash key does not exist
      *   in session.
      * @throws \UnexpectedValueException If value for flash settings key is not an array.
      */
     public function render($key = 'flash', array $options = [])
     {
         if (!$this->request->session()->check("Flash.$key")) {
-            return;
+            return null;
         }
 
         $flash = $this->request->session()->read("Flash.$key");

src/View/Helper/FormHelper.php

@@ -546,12 +546,12 @@ class FormHelper extends Helper
      *    generating the hash, else $this->fields is being used.
      * @param array $secureAttributes will be passed as HTML attributes into the hidden
      *    input elements generated for the Security Component.
-     * @return void|string A hidden input field with a security hash
+     * @return string|null A hidden input field with a security hash
      */
     public function secure(array $fields = [], array $secureAttributes = [])
     {
         if (empty($this->request['_Token'])) {
-            return;
+            return null;
         }
         $locked = [];
         $unlockedFields = $this->_unlockedFields;

src/View/View.php

@@ -354,7 +354,7 @@ class View implements EventDispatcherInterface
      * Get/set path for templates files.
      *
      * @param string $path Path for template files. If null returns current path.
-     * @return string|void
+     * @return string|null
      */
     public function templatePath($path = null)
     {
@@ -369,7 +369,7 @@ class View implements EventDispatcherInterface
      * Get/set path for layout files.
      *
      * @param string $path Path for layout files. If null returns current path.
-     * @return string|void
+     * @return string|null
      */
     public function layoutPath($path = null)
     {
@@ -386,7 +386,7 @@ class View implements EventDispatcherInterface
      * automatically applied to rendered templates.
      *
      * @param bool $autoLayout Boolean to turn on/off. If null returns current value.
-     * @return bool|void
+     * @return bool|null
      */
     public function autoLayout($autoLayout = null)
     {
@@ -401,7 +401,7 @@ class View implements EventDispatcherInterface
      * The view theme to use.
      *
      * @param string $theme Theme name. If null returns current theme.
-     * @return string|void
+     * @return string|null
      */
     public function theme($theme = null)
     {
@@ -417,7 +417,7 @@ class View implements EventDispatcherInterface
      * filename in /app/Template/<SubFolder> without the .ctp extension.
      *
      * @param string $name Template file name to set. If null returns current name.
-     * @return string|void
+     * @return string|null
      */
     public function template($name = null)
     {
@@ -434,7 +434,7 @@ class View implements EventDispatcherInterface
      * without the .ctp extension.
      *
      * @param string $name Layout file name to set. If null returns current name.
-     * @return string|void
+     * @return string|null
      */
     public function layout($name = null)
     {
@@ -556,7 +556,7 @@ class View implements EventDispatcherInterface
      *
      * @param string|null $view Name of view file to use
      * @param string|null $layout Layout to use.
-     * @return string|void Rendered content or null if content already rendered and returned earlier.
+     * @return string|null Rendered content or null if content already rendered and returned earlier.
      * @throws \Cake\Core\Exception\Exception If there is an error in the view.
      * @triggers View.beforeRender $this, [$viewFileName]
      * @triggers View.afterRender $this, [$viewFileName]
@@ -564,7 +564,7 @@ class View implements EventDispatcherInterface
     public function render($view = null, $layout = null)
     {
         if ($this->hasRendered) {
-            return;
+            return null;
         }
 
         if ($layout !== null) {