PHPDoc: @return void notwendig?

Ist es wirklich notwendig, so etwas zu tun:

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

Ich habe einige Methoden, die keinen Rückgabewert haben, und es scheint wirklich überflüssig, so etwas in den Kommentar aufzunehmen. Wäre es eine schlechte Form, es wegzulassen?

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.

Laut phpDocumentor ist @return void gültig:

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

... dieser Typ wird normalerweise nur verwendet, wenn der Rückgabetyp einer Methode oder Funktion definiert wird. Die grundlegende Definition ist, dass das mit diesem Typ angegebene Element keinen Wert enthält und der Benutzer sich nicht auf einen abgerufenen Wert verlassen sollte.

Zum Beispiel:

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

Im obigen Beispiel ist keine return-Anweisung angegeben und somit wird der Rückgabewert nicht bestimmt.

Quelle: http://www.phpdoc.org/docs/latest/for-users/phpdoc/types.html ( archivierte Seite ).

Ich muss meine Antwort aufgrund von etwas bearbeiten, das ich kürzlich gelernt habe.

Die Verwendung von @return voidanstelle von @return nullhat 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ückgibt NULL. 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 voidhat 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/

Ab PHP 7.1 voidist 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 voidMethoden von den Methoden zu unterscheiden, die möglicherweise alles zurückgeben, aber @returnfahrlässig keinen Eintrag im Dokumentblock haben.

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

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