example - phpdocumentor download windows

PHPDoc: ¿es necesario @return void?

Question

¿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 mala forma dejarlo fuera?

Answer 1

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

Siempre lo agregaría en el docblock.

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

Answer 2

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

Answer 3

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

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

... este tipo comúnmente se usa solo cuando se define el tipo de devolución 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 devolución y, por lo tanto, no se determina el valor de retorno.

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

Answer 4

Si deja en claro la documentación, déjela, pero no es estrictamente necesario. Es una decisión totalmente subjetiva.

Personalmente, lo dejaría fuera.

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

@return [type description] Esta etiqueta no se debe usar para constructores o métodos definidos con un tipo de retorno nulo.

El sitio web phpdoc.org dice:

@return datatype description
@return datatype1 | datatype2 descripción

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

El tipo de datos debe ser un tipo válido de PHP (int, string, bool, etc.), un nombre de clase para el tipo de objeto devuelto, o simplemente "mixed". Si desea mostrar explícitamente múltiples posibles tipos de devolución, enumere los delimitados por tubería sin espacios (por ejemplo, "@return int | cadena"). Si se utiliza un nombre de clase como el 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 múltiples valores posibles, sepárelos con el | carácter, y phpDocumentor analizará cualquier nombre de clase en el valor de retorno. phpDocumentor mostrará la descripción opcional sin modificaciones.

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

Answer 5

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

Usar @return void 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 sirve 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 void para indicar al desarrollador que 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 vuelve aún más interesante si colocamos las llamadas de 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 debería 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/