PHPDoc: ¿@return void es necesario?

81

¿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?

Richie Márquez
fuente

Respuestas:

91

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.

Jonathan Fingland
fuente
¿Agregarlo hace algo? Creo en PHPDoc si no documenta un tipo de retorno, automáticamente lo asume voidy lo coloca en la firma del método en los documentos.
Marc W
@Marc W: ver mi edición. no solo no es necesario, se supone que no debe usarse.
Jonathan Fingland
2
Puede haber cambiado desde 2010, pero actualmente phpdoc.org dice: "funciones y métodos sin un returnvalor, la etiqueta @return PUEDE omitirse aquí, en cuyo caso @return void está implícito".
TFennis
@TFennis Gracias. Dejaré la cita heredada como está, pero parece que phpdoc simplemente está siendo más tolerante con la cantidad de desarrolladores que la estaban usando. Noto que la página de wikipedia ahora dice [cita requerida] para la declaración sobre evitar @return void.
Jonathan Fingland
Desde mi punto de vista, esta respuesta está desactualizada. voidDesde PHP 7.1, el tipo es un tipo de retorno válido y, como señala @tivnet en la respuesta a continuación, también es un tipo válido para phpDocs según phpDocumentor.
Ernesto Allely
50

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 ).

tivnet
fuente
4
Aquí es donde señalo que 'esta es la respuesta correcta'. :)
Error
3
La respuesta correcta debe cambiarse a esto.
BadHorsie
4
De hecho, esta sería la mejor respuesta aquí. También es parte del estándar PSR-5 que se avecina. Yo iría con el siguiente enfoque para la programación semántica significativa: dereuromark.de/2015/10/05/return-null-vs-return-void
marca el
15

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/

Molinillo de carne
fuente
Buen punto, pero si la función sale, significa que no regresa null. Estoy en lo cierto? Creo que en ese caso @returns voides la mejor opción.
Tamás Barta
Una función siempre regresará NULLsi no devuelve nada más. Una función que usa exit()o algo como esto todavía está regresando NULLpero no la recibirá porque PHP salta directamente a la fase de apagado ignorando su código.
Fleshgrinder
Interesante. Habría asumido, si lo que dices es cierto, los finallybloques se ejecutan cuando llamo exit. No es una correlación directa entre los dos, pero no se siente bien. Gracias por iluminarme. :)
Tamás Barta
Una mejor redacción hubiera sido: “[…] todavía regresaría NULL[…]”. Supongo que podemos comparar exitcon goto simplemente diciéndole a PHP que deje de ejecutar el código actual y salte directamente a la fase de apagado, ignorando cualquier código a partir de este punto (por lo tanto, goto en un ámbito más externo [global] que cualquier función actual está anidada) . Un bloque finalmente no se ejecuta, pero muchas otras funciones sí (por ejemplo register_shutdown, __destruct).
Fleshgrinder
Eso parece tener más sentido, y eso es lo que pensé al principio. También decidí usar @returns voidpara indicar que la función termina toda la ejecución del script, por ejemplo, en una redirección HTTP. Además, sería mejor usarlo para indicar que la función no está diseñada para devolver nada.
Tamás Barta
7

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.

Dimitris Baltas
fuente
3

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();
}
Dejv
fuente
0

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

Narrim
fuente