PHPDoc: ¿@return void es necesario?

¿Es realmente necesario hacer algo como esto?

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

Tengo bastantes métodos que no tienen un valor de retorno, y parece realmente redundante poner algo como esto en el comentario. ¿Se consideraría de mala educación dejarlo fuera?

Si lo deja claro para la documentación, déjelo, pero no es estrictamente necesario. Es una decisión completamente subjetiva.

Personalmente, lo dejaría fuera.

EDITAR
Estoy corregido. Después de buscar un poco en Google, la página de wikipedia dice:

@return [descripción del tipo] Esta etiqueta no debe usarse para constructores o métodos definidos con un tipo de retorno vacío.

El sitio web phpdoc.org dice:

@return descripción del tipo de datos
@return datatype1 | descripción del tipo de datos2

La etiqueta @return se usa para documentar el valor de retorno de funciones o métodos. @returns es un alias de @return para admitir formatos de etiqueta de otros documentadores automáticos

El tipo de datos debe ser un tipo PHP válido (int, string, bool, etc.), un nombre de clase para el tipo de objeto devuelto o simplemente "mixto". Si desea mostrar explícitamente varios tipos de retorno posibles, enumérelos delimitados por tuberías sin espacios (por ejemplo, "@return int | string"). Si se utiliza un nombre de clase como tipo de datos en la etiqueta @return, phpDocumentor creará automáticamente un enlace a la documentación de esa clase. Además, si una función devuelve varios valores posibles, sepárelos mediante la | character, y phpDocumentor analizará cualquier nombre de clase en el valor de retorno. phpDocumentor mostrará la descripción opcional sin modificar.

Así que ... Basándome en eso, diría que deja el vacío. No es estándar, al menos.

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

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

... este tipo se usa comúnmente solo 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 no debe confiar en ningún valor recuperado.

Por ejemplo:

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

En el ejemplo anterior no se especifica ninguna declaración de retorno y, por lo tanto, el valor de retorno no se determina.

Fuente: http://www.phpdoc.org/docs/latest/for-users/phpdoc/types.html ( página archivada ).

Tengo que editar mi respuesta por algo que he aprendido recientemente.

Usar en @return voidlugar de @return nulltiene 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 regresará NULL, ya que PHP siempre regresa 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. Los IDE pueden usar la información documentada de @return voidpara indicar al desarrollador que se usa un valor de retorno que no tiene ningún propósito.

<?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 vuelve aún más interesante si ponemos las llamadas a funciones en un condicional.

<?php

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

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

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

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

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

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

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

Otro beneficio de escribirlo es diferenciar los voidmétodos de los métodos que pueden devolver cualquier cosa pero no tienen una @returnentrada 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();
}

Personalmente, creo que lo que falta en esto es que documentar los retornos de una función es importante. Actualmente los estándares no tienen documentación para funciones que nunca regresan ... por lo tanto, un return void es una forma de decir que sí, esta función realmente regresa.

Considere este bloque de código

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

Claramente, el uso de @return al menos indica que la función regresa