PHPDoc: @return void necessary?

Question

Is it really necessary do something like this:

/**
 * ...
 * 
 * @return void
 */

I have quite a few methods that don\'t have a return valu

Answer 1

If it makes it clear for the documentation, then leave it in, but it isn't strictly necessary. It's an entirely subjective decision.

Personally, I would leave it out.

EDIT
I stand corrected. After a little googling, the wikipedia page says:

@return [type description] This tag should not be used for constructors or methods defined with a void return type.

The phpdoc.org website says:

@return datatype description
@return datatype1|datatype2 description

The @return tag is used to document the return value of functions or methods. @returns is an alias for @return to support tag formats of other automatic documentors

The datatype should be a valid PHP type (int, string, bool, etc), a class name for the type of object returned, or simply "mixed". If you want to explicitly show multiple possible return types, list them pipe-delimited without spaces (e.g. "@return int|string"). If a class name is used as the datatype in the @return tag, phpDocumentor will automatically create a link to that class's documentation. In addition, if a function returns multiple possible values, separate them using the | character, and phpDocumentor will parse out any class names in the return value. phpDocumentor will display the optional description unmodified.

Sooo... Based on that, I would say leave out the void. It's non-standard, at least.

Answer 2

As of php 7.1, void is a valid return type and can be enforced on a function.

I would always add it on the docblock.

Another benefit of writing it, is to differentiate the void methods from the methods that may return anything but don't have a @return entry on the docblock by negligence.

Answer 3

Personally, I think the big thing missing from this is that documenting a function returns at all is important. Currently standards dont have any documentation for functions that never return....hence a return void is way of saying yes this function does actually return.

Consider this code block

<?php

/**
 * @return void
 */
function return_void() {
    echo "foo";
}

/**
 * @return null|string
 */
function return_sometimes() {
    if ($this->condition()) {
        return "foo";
    }
}

/**
* This function actually doesnt return at all - it kills the script
**/
function noreturn() {
     //do somthing then
     die(); //or exit()
}

Clearly the use of @return at least indicates the function does return

Answer 4

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/

Answer 5

Here is how I understand and use PhpDocumentor annotations:

<?php

/**
 * This method always returns string.
 * @return string
 */
public function useCase1()
{
    return 'foo';
}

/**
 * This method returns 2 data types so list them both using pipeline separator.
 * @return string|false
 */
public function useCase2()
{
    if ($this->foo === 1) {
        return 'foo';
    }
    return false;
}

/**
 * This method performs some operation and does not return anything so no return
 * annotation is needed.
 */
public function useCase3()
{
    $this->doOperation();
    $this->doAnotherOperation();
}

/**
 * If condition passes method returns void. If condition does not pass it returns
 * nothing so I think that specifying the return annotation with void is in space. :)
 * @return void
 */
public function useCase4()
{
    if ($this->foo === 1) {
        $this->doOperation();
        return;
    }
    $this->doAnotherOperation();
}

Answer 6

According to phpDocumentor, @return void is valid:

http://www.phpdoc.org/docs/latest/guides/types.html#keywords

... this type is commonly only used when defining the return type of a method or function. The basic definition is that the element indicated with this type does not contain a value and the user should not rely on any retrieved value.

For example:

 /**
  * @return void
  */
 function outputHello()
 {
     echo 'Hello world';
 }

In the example above no return statement is specified and thus is the return value not determined.

Source: http://www.phpdoc.org/docs/latest/for-users/phpdoc/types.html (archived page).