I have to edit my answer because of something I have learned recently.
Using @return void instead of @return null has a very special meaning, consider the following two examples of PHP code.
<?php
/**
* @return void
*/
function return_never() {
echo "foo";
}
/**
* @return null|string
*/
function return_sometimes() {
if ($this->condition()) {
return "foo";
}
}
In the first example PHP will actually return NULL, since PHP always returns NULL. But the returned value is of no use to the caller since it does not say anything about what the function did. IDEs can use the documented information of @return void to indicate the developer that a return values is used which serves no purpose.
<?php
$foo1 = return_never();
$foo2 = return_sometimes();
The first call is senseless since the variable will always contain NULL, the second one might actually contain something. This is becoming even more interesting if we put the function calls into a conditional.
<?php
if (($foo1 = return_never())) {
// Dead code
var_dump($foo1);
}
if (($foo2 = return_sometimes())) {
var_dump($foo2);
}
As you can see, @return void has its use cases and should be used if applicable.
Also note that it is going to be a part of the upcoming PHP PSR-5 standard.[1]
[1] http://www.php-fig.org/psr/