Wenn es für die Dokumentation klar ist, lassen Sie es in, aber es ist nicht unbedingt notwendig. Es ist eine völlig subjektive Entscheidung.
Persönlich würde ich es weglassen.
EDIT
Ich stehe korrigiert. Nach ein wenig googeln heißt es auf der Wikipedia-Seite :
@return [Typbeschreibung] Dieses Tag sollte nicht für Konstruktoren oder Methoden verwendet werden, die mit einem ungültigen Rückgabetyp definiert sind.
Auf der Website phpdoc.org heißt es:
Beschreibung
des Datentyps @return Beschreibung des Datentyps @ return1 | Beschreibung des Datentyps2
Das @ return-Tag wird verwendet, um den Rückgabewert von Funktionen oder Methoden zu dokumentieren. @returns ist ein Alias für @return zur Unterstützung von Tag-Formaten anderer automatischer Dokumentatoren
Der Datentyp sollte ein gültiger PHP-Typ (int, string, bool usw.), ein Klassenname für den zurückgegebenen Objekttyp oder einfach "gemischt" sein. Wenn Sie mehrere mögliche Rückgabetypen explizit anzeigen möchten, listen Sie sie ohne Leerzeichen auf (z. B. "@return int | string"). Wenn ein Klassenname als Datentyp im @ return-Tag verwendet wird, erstellt phpDocumentor automatisch einen Link zur Dokumentation dieser Klasse. Wenn eine Funktion mehrere mögliche Werte zurückgibt, trennen Sie diese außerdem mit | Zeichen, und phpDocumentor analysiert alle Klassennamen im Rückgabewert. phpDocumentor zeigt die optionale Beschreibung unverändert an.
Sooo ... Basierend darauf würde ich sagen, lass die Leere weg. Zumindest ist es nicht Standard.
void
und in die Methodensignatur in den Dokumenten eingefügt.return
Wert, das @ return-Tag kann hier weggelassen werden. In diesem Fall wird @return void impliziert."@return void
.void
ist seit PHP 7.1 ein gültiger Rückgabetyp und wie @tivnet in der Antwort unten zeigt, ist er laut phpDocumentor auch ein gültiger Typ für phpDocs.Laut phpDocumentor ist @return void gültig:
http://www.phpdoc.org/docs/latest/guides/types.html#keywords
Quelle: http://www.phpdoc.org/docs/latest/for-users/phpdoc/types.html ( archivierte Seite ).
quelle
Ich muss meine Antwort aufgrund von etwas bearbeiten, das ich kürzlich gelernt habe.
Die Verwendung von
@return void
anstelle von@return null
hat eine ganz besondere Bedeutung. Betrachten Sie die folgenden zwei Beispiele für PHP-Code.<?php /** * @return void */ function return_never() { echo "foo"; } /** * @return null|string */ function return_sometimes() { if ($this->condition()) { return "foo"; } }
Im ersten Beispiel wird PHP tatsächlich zurückgegeben
NULL
, da PHP immer zurückgibtNULL
. Der zurückgegebene Wert ist für den Aufrufer jedoch nicht von Nutzen, da er nichts darüber aussagt, was die Funktion getan hat. IDEs können die dokumentierten Informationen von verwenden@return void
, um dem Entwickler anzuzeigen, dass Rückgabewerte verwendet werden, die keinen Zweck erfüllen.<?php $foo1 = return_never(); $foo2 = return_sometimes();
Der erste Aufruf ist sinnlos, da die Variable immer enthält
NULL
, der zweite möglicherweise tatsächlich etwas. Dies wird noch interessanter, wenn wir die Funktionsaufrufe in eine Bedingung setzen.<?php if (($foo1 = return_never())) { // Dead code var_dump($foo1); } if (($foo2 = return_sometimes())) { var_dump($foo2); }
Wie Sie sehen können,
@return void
hat seine Anwendungsfälle und sollte gegebenenfalls verwendet werden.Beachten Sie auch, dass es Teil des kommenden PHP PSR-5-Standards sein wird. [1]
[1] http://www.php-fig.org/psr/
quelle
null
. Habe ich recht? Ich denke, in diesem Fall@returns void
ist die beste Option.NULL
wenn Sie nichts anderes zurückgeben. Eine Funktion, dieexit()
oder etwas Ähnliches verwendet, kehrt immer noch zurück,NULL
aber Sie erhalten sie nicht, da PHP direkt in die Abschaltphase springt und Ihren Code ignoriert.finally
Blöcke ausgeführt, wenn ich anrufeexit
. Keine direkte Korrelation zwischen den beiden, aber es fühlt sich nicht richtig an. Danke, dass du mich aufgeklärt hast. :)NULL
[…]“. Ich denke, wir könnenexit
mit goto vergleichen, indem wir PHP einfach anweisen, die Ausführung des aktuellen Codes zu beenden und direkt in die Shutdown-Phase zu springen, wobei jeder Code von diesem Punkt an ignoriert wird (also goto in einem äußereren Bereich [global] als jede aktuelle Funktion verschachtelt ist). . Ein finally - Block wird nicht ausgeführt, sondern auch viele andere Funktionen (zBregister_shutdown
,__destruct
).@returns void
anzuzeigen, dass die Funktion die gesamte Skriptausführung beendet, beispielsweise bei einer HTTP-Umleitung. Es wäre auch immer noch besser zu verwenden, um anzuzeigen, dass die Funktion nicht dafür ausgelegt ist, etwas zurückzugeben.Ab PHP 7.1
void
ist ein gültiger Rückgabetyp und kann für eine Funktion erzwungen werden.Ich würde es immer auf dem Docblock hinzufügen.
Ein weiterer Vorteil des Schreibens besteht darin, die
void
Methoden von den Methoden zu unterscheiden, die möglicherweise alles zurückgeben, aber@return
fahrlässig keinen Eintrag im Dokumentblock haben.quelle
So verstehe und verwende ich PhpDocumentor-Anmerkungen:
<?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(); }
quelle
Persönlich denke ich, dass das große Problem dabei ist, dass es wichtig ist, die Rückgabe einer Funktion überhaupt zu dokumentieren. Derzeit haben Standards keine Dokumentation für Funktionen, die niemals zurückkehren. Daher ist eine Rückgabelücke eine Möglichkeit zu sagen, dass diese Funktion tatsächlich zurückkehrt.
Betrachten Sie diesen Codeblock
<?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() }
Die Verwendung von @return zeigt eindeutig an, dass die Funktion zurückkehrt
quelle