PHPDoc:@return void notwendig?

Question

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 zu schreiben.Wäre es eine schlechte Form, es wegzulassen?

Answer 1

Wenn es für die Dokumentation klar ist, lassen Sie es drin, aber es ist nicht unbedingt notwendig.Es ist eine völlig subjektive Entscheidung.

Ich persönlich würde es weglassen.

BEARBEITEN
Ich stehe korrigiert.Nach ein wenig Googeln kam das Wikipedia-Seite sagt:

@return [Typbeschreibung] Dieses Tag sollte nicht benutzt werden für Konstruktoren oder Methoden, die mit einem void-Rückgabetyp definiert sind.

Auf der Website phpdoc.org heißt es:

Beschreibung des @return-Datentyps
@return Datentyp1|Datentyp2 Beschreibung

Das @return-Tag wird verwendet, um den Rückgabewert von Funktionen oder Methoden zu dokumentieren.@returns ist ein Alias ​​für @return, um Tag-Formate anderer automatischer Dokumentierer zu unterstützen

Der Datentyp sollte ein gültiger PHP-Typ sein (int, string, bool usw.), ein Klassenname für den Typ des zurückgegebenen Objekts, oder einfach „gemischt“.Wenn Sie mehrere mögliche Rückgabetypen explizit anzeigen möchten, listen Sie sie durch Pipe-Trennzeichen 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 sie außerdem mit dem | Charakter und Phpdocumentor analysieren alle Klassennamen im Rückgabewert.phpDocumentor zeigt die optionale Beschreibung unverändert an.

Sooo...Auf dieser Grundlage würde ich sagen, lassen Sie die Lücke weg.Zumindest ist es kein Standard.

Answer 2

Nach phpDocumentor, @return nichtig gilt:

http://www.phpdoc.org/docs/latest/ Führer / types.html # keywords

  

...   Diese Art wird häufig verwendet, nur bei der Definition des Rückgabetypen   Ein Verfahren oder eine Funktion. Die grundlegende Definition ist, dass das Element   mit dieser Art angezeigt keinen Wert enthalten, und der Benutzer sollte   nicht verlassen sich auf jeden abgefragten Wert.

     

Zum Beispiel:

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

     

Im Beispiel oben no return-Anweisung angegeben wird, und somit ist die   Rückgabewert nicht bestimmt.

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

Answer 3

Ich habe meine Antwort zu bearbeiten, weil etwas, das ich vor kurzem gelernt haben.

Mit @return void statt @return null hat eine ganz besondere Bedeutung, 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 PHP tatsächlich NULL zurückkehren, da PHP immer NULL zurückgibt. Aber der zurückgegebene Wert ist nicht von Nutzen für den Anrufer, da es sagt nichts darüber, was die Funktion hat. IDEs können die dokumentierten Informationen von @return void verwenden die Entwickler, um anzuzeigen, dass ein Rückgabewerte verwendet wird, die keinen Zweck dient.

<?php

$foo1 = return_never();

$foo2 = return_sometimes();

Der erste Anruf sinnlos ist, da die Variable immer NULL enthalten wird, könnte die zweite tatsächlich etwas enthalten. Dies ist immer noch interessanter, wenn wir die Funktionsaufrufe in eine bedingten 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 ggf. verwendet werden.

Beachten Sie auch, dass es ein Teil des kommenden PHP PSR-5-Standard sein wird. ^[1]

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

Answer 4

Ab PHP 7.1, void ist ein gültiger Rückgabetyp und kann auf einer Funktion erzwungen werden.

Ich würde immer fügen Sie es auf dem Docblock.

Ein weiterer Vorteil des Schreibens ist die void Methoden von den Methoden zu unterscheiden, die etwas zurückgeben kann, aber nicht über einen @return Eintrag auf der Docblock durch Fahrlässigkeit.

Answer 5

Hier ist, wie ich verstehen und zu verwenden 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();
}