wake-up-neo.com

PHPDoc: @return nichtig 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, sie wegzulassen?

76
Richie Marquez

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

Persönlich würde ich es weglassen.

[~ # ~] edit [~ # ~]
Ich stehe korrigiert. Nach ein wenig googeln sagt die 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 phpdoc.org-Website heißt es:

@return Beschreibung des Datentyps
@ return datatype1 | datatype2 description

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 type (int, string, bool, etc), ein Klassenname für das sein Typ des zurückgegebenen Objekts oder einfach "gemischt" Wenn Sie mehrere mögliche Rückgabetypen explizit anzeigen möchten, listen Sie diese ohne Leerzeichen mit Pipe-Trennzeichen auf (z. B. "@return int | string"). Wenn ein Klassenname als Datentyp in verwendet wird Mit dem @ return-Tag erstellt phpDocumentor automatisch einen Link zur Dokumentation dieser Klasse. Wenn eine Funktion mehrere mögliche Werte zurückgibt, trennen Sie diese mit dem Zeichen |, und phpDocumentor analysiert alle Klassennamen im Rückgabewert. phpDocumentor wird angezeigt die optionale Beschreibung unverändert.

Sooo ... Aufgrund dessen würde ich sagen, die Leere weglassen. Zumindest ist es nicht Standard.

88

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.

Beispielsweise:

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

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

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

45
tivnet

Ich muss meine Antwort bearbeiten, weil ich etwas kürzlich gelernt habe.

Mit @return void Anstatt 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 gibt PHP tatsächlich NULL zurück, da PHP immer NULL zurückgibt. Der zurückgegebene Wert ist jedoch von Kein Nutzen für den Aufrufer, da er nichts über die Funktionsweise der Funktion aussagt. IDEs können die dokumentierten Informationen von @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 NULL enthält, der zweite könnte tatsächlich etwas enthalten. 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 du sehen kannst, @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/

13
Fleshgrinder

Ab PHP 7.1 kann void ist ein gültiger Rückgabetyp und für eine Funktion erzwungen werden.

Ich würde immer auf dem docblock hinzufügen.

Ein weiterer Vorteil des Schreibens besteht darin, dass die void -Methoden von den Methoden unterschieden werden, die aus Versehen alles zurückgeben, aber keinen @return - Eintrag im Dokumentblock haben.

5
Dimitris Baltas

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