franz-josef-kaiser/WordPress-GitHub-Plugin-Updater — comment on commit c0699239965d2c5e850b89d9f8ad5ded7a755bdd
File: updater.php line 92
By GaryJones:

What benefit does having a tag that says that nothing is returned, when you can save a line of code and state that the return keyword is not present when the `@return` tag is not present.

Again, the draft [PHPDoc PSR](https://github.com/mvriel/Docblox/blob/develop/docs/PSR.md) says it is optional.

The [Wikipedia](http://en.wikipedia.org/wiki/PHPDoc) page states that the `@return` tag should not be used for a void / no return value.

The source code examples 2 and 3 on the phpdoc.org website clearly omit the `@return` tag when there is no return keyword. It also says says:

> The @return tag is used to document the return value of functions or methods.

There is no return value, so there shouldn't be a `@return` tag, just the same as you wouldn't include a `@param` tag when there is no arguments, or a `@global` tag when there's no global being used.

> The datatype should be a valid PHP type (int, string, bool, etc), a class name for the type of object returned, or simply "mixed".

void is not a valid PHP type. At best, it's a pseudo-type, and only used to describe PHP functions itself for the purposes of documenting the C code that PHP is actually written in. It's not suitable for documenting PHP code.

The [PHP Manual](http://php.net/manual/en/functions.returning-values.php) clearly states that "If the return() is omitted the value NULL will be returned.". NULL != void, so by including `@return void` you're actually giving wrong documentation, which is worse than no documentation.