PHPDoc: @return void ¿es necesario?

Según phpDocumentor, @return void es válido:

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

... este tipo solo se usa comúnmente cuando se define el tipo de retorno de un método o función. La definición básica es que el elemento indicado con este tipo no contiene un valor y el usuario debe no confiar en ningún valor recuperado.

Por ejemplo:

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

En el ejemplo anterior no return statement es especificado y por lo tanto es el valor devuelto no determinado.

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

Tengo que editar mi respuesta debido a algo que he aprendido recientemente.

Usar @return void en lugar de @return null tiene un significado muy especial, considere los siguientes dos ejemplos de código PHP.

<?php

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

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

En el primer ejemplo PHP realmente devolverá NULL, ya que PHP siempre devuelve NULL. Pero el valor devuelto no es de utilidad para la persona que llama, ya que no dice nada sobre lo que hizo la función. IDEs puede utilizar la información documentada de @return void para indicar al desarrollador que un se utilizan valores de retorno que no sirven para nada.

<?php

$foo1 = return_never();

$foo2 = return_sometimes();

La primera llamada no tiene sentido ya que la variable siempre contendrá NULL, la segunda podría contener algo. Esto se está volviendo aún más interesante si ponemos las llamadas a la función en un condicional.

<?php

if (($foo1 = return_never())) {
    // Dead code
    var_dump($foo1);
}

if (($foo2 = return_sometimes())) {
    var_dump($foo2);
}

Como puede ver, @return void tiene sus casos de uso y debe usarse si corresponde.

También tenga en cuenta que va a ser parte del próximo estándar PHP PSR-5.^[1]

[1] http://www.php-fig.org/psr /

A partir de php 7.1, void es un tipo de retorno válido y se puede aplicar en una función.

Yo siempre añadir en el bloque de documentación.

Otro beneficio de escribirlo, es diferenciar los métodos void de los métodos que pueden devolver cualquier cosa pero no tienen una entrada @return en el docblock por negligencia.

Así es como entiendo y uso las anotaciones de phpDocumentor:

<?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();
}