web-dev-qa-db-fra.com

PHPDoc: @return void nécessaire?

Est-il vraiment nécessaire de faire quelque chose comme ça:

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

J'ai pas mal de méthodes qui n'ont pas de valeur de retour, et il semble vraiment superflu de mettre quelque chose comme ça dans le commentaire. Serait-il considéré comme une mauvaise forme de le laisser de côté?

phpreturn-valuephpdoc
76
Richie Marquez

Si cela est clair pour la documentation, laissez-le, mais ce n'est pas strictement nécessaire. C'est une décision entièrement subjective.

Personnellement, je laisserais ça de côté.

[~ # ~] modifier [~ # ~]
Je me suis trompé. Après un peu de recherche sur Google, la page wikipedia dit:

@return [type description] Cette balise ne doit pas être utilisée pour les constructeurs ou les méthodes définies avec un type de retour void.

Le site Web phpdoc.org dit:

Description du type de données @return
@ return datatype1 | datatype2 description

La balise @return est utilisée pour documenter la valeur de retour des fonctions ou des méthodes. @returns est un alias de @return pour prendre en charge les formats de balises d'autres documenteurs automatiques

Le type de données doit être un PHP type (int, string, bool, etc.) valide, un nom de classe pour le type d'objet renvoyé, ou simplement "mixte". Si vous souhaitez afficher explicitement plusieurs types de retour possibles, répertoriez-les délimités par des tuyaux sans espaces (par exemple, "@return int | string"). Si un nom de classe est utilisé comme type de données dans la balise @return, phpDocumentor créera automatiquement un lien vers la documentation de cette classe. De plus, si une fonction renvoie plusieurs valeurs possibles, séparez-les en utilisant le caractère |, et phpDocumentor analysera tous les noms de classe dans la valeur de retour. phpDocumentor affichera la description facultative non modifiée.

Sooo ... Sur cette base, je dirais laisser de côté le vide. Ce n'est pas standard du moins.

88
Jonathan Fingland

Selon phpDocumentor, @return void est valide:

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

... ce type est généralement utilisé uniquement lors de la définition du type de retour d'une méthode ou d'une fonction. La définition de base est que l'élément indiqué avec ce type ne contient pas de valeur et l'utilisateur ne doit pas compter sur une valeur récupérée.

Par exemple:

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

Dans l'exemple ci-dessus, aucune instruction de retour n'est spécifiée et la valeur de retour n'est donc pas déterminée.

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

45
tivnet

Je dois modifier ma réponse à cause de quelque chose que j'ai appris récemment.

En utilisant @return void au lieu de @return null a une signification très spéciale, considérons les deux exemples suivants de PHP.

<?php

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

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

Dans le premier exemple PHP retournera en fait NULL, puisque PHP renvoie toujours NULL. Mais la valeur renvoyée est de aucune utilité à l'appelant car il ne dit rien sur ce que la fonction a fait. Les IDE peuvent utiliser les informations documentées de @return void pour indiquer au développeur qu'une valeur de retour est utilisée, ce qui ne sert à rien.

<?php

$foo1 = return_never();

$foo2 = return_sometimes();

Le premier appel est insensé puisque la variable contiendra toujours NULL, le second pourrait en fait contenir quelque chose. Cela devient encore plus intéressant si nous mettons les appels de fonction au conditionnel.

<?php

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

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

Comme vous pouvez le voir, @return void a ses cas d'utilisation et doit être utilisé le cas échéant.

Notez également que cela fera partie de la prochaine norme PHP PSR-5.[1]

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

13
Fleshgrinder

Depuis php 7.1, void est un type de retour valide et peut être appliqué sur une fonction.

Je voudrais toujours l'ajouter sur le docblock.

Un autre avantage de l'écrire est de différencier les méthodes void des méthodes qui peuvent renvoyer n'importe quoi mais n'ont pas de @return entrée sur le docblock par négligence.

5
Dimitris Baltas

Voici comment je comprends et utilise les annotations 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();
}
2
Dejv