PHPDoc: @return void nécessaire?

Question

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

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

J'ai quelques méthodes qui n'ont pas de valeur de retour, et il semble vraiment redondant de mettre quelque chose comme cela dans le commentaire. Serait-il être considéré comme une mauvaise forme de la quitter?

Answer 1

Si il est clair pour la documentation, puis de le laisser, mais il n'est pas strictement nécessaire. C'est une décision subjective.

Personnellement, je le laisserais.

MODIFIER
Je corrige la position des mains. Après un liitle googleing, la page wikipédia dit:

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

L'phpdoc.org site web dit:

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

Le @return balise est utilisée pour documenter la valeur de retour de fonctions ou de méthodes. @retourne est un alias pour @return pour soutenir les formats de balises d'autres automatique documenteurs

Le type de données doit être valide PHP de type (int, string, bool, etc), un nom de classe pour le type d'objet renvoyé, ou tout simplement "mixtes". Si vous souhaitez afficher explicitement plusieurs types de retour, en dresser la liste pipe-virgules sans espaces (par exemple, "@return int|string"). Si un nom de classe est utilisée comme type de données dans le @return balise, phpDocumentor va automatiquement créer un lien vers cette classe de la documentation. En outre, si une fonction retourne plusieurs valeurs possibles, les séparer par le caractère|, et phpDocumentor permettra d'analyser les noms de classe dans la valeur de retour. phpDocumentor affiche une description facultative non modifiée.

Sooo..... Sur cette base, je dirais de laisser le vide. Il est non-standard, au moins.

Answer 2

Selon phpDocumentor, @return void est valide:

http://www.phpdoc.org/docs/latest/for-users/phpdoc/types.html

... ce type n'est utilisée que lors de la définition du type de retour de 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 que l'utilisateur doit ne pas compter sur une quelconque valeur récupérée.

Par exemple:

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

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

Answer 3

La raison pourquoi @return void n'est pas valide en PHP, c'est parce que chaque fonction renvoie toujours NULL. Vous pouvez facilement tester vous-même.

function do_i_return_something() {}

var_dump(do_i_return_something());

Si vous exécutez le code var_dump() imprime NULL.

Si vous voulez le document a valeur de retour des fonctions qui n'ont pas de retour dans le corps pour @return null.