PHPDoc: @ return void konieczne?

Zgodnie z phpDocumentor, @ return void jest poprawny:

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

... ten typ jest powszechnie używany tylko przy definiowaniu typu zwrotu metoda lub funkcja. Podstawową definicją jest to, że element wskazane tym typem nie zawiera wartości i użytkownik powinien nie polegaj na żadnej odzyskanej wartości.

Na przykład:

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

W powyższym przykładzie żadna Instrukcja return nie jest określone i tak jest wartość zwracana nie została ustalona.

Źródło: http://www.phpdoc.org/docs/latest/for-users/phpdoc/types.html ( zarchiwizowana Strona ).

Muszę edytować swoją odpowiedź z powodu czegoś, czego się ostatnio nauczyłem.

Użycie @return void zamiast @return null ma bardzo szczególne znaczenie, rozważ następujące dwa przykłady kodu PHP.

<?php

/**
 * @return void
 */
function return_never() {
    echo "foo";
}

/**
 * @return null|string
 */
function return_sometimes() {
    if ($this->condition()) {
        return "foo";
    }
}

W pierwszym przykładzie PHP zwróci NULL, ponieważ PHP zawsze zwraca NULL. Zwracana wartość jest jednak bezużyteczna dla wywołującego, ponieważ nie mówi nic o tym, co zrobiła funkcja. Ide mogą wykorzystać udokumentowane informacje @return void, aby wskazać deweloperowi, że zwracane wartości są używane, co nie służy żadnemu celowi.

<?php

$foo1 = return_never();

$foo2 = return_sometimes();

Pierwsze wywołanie jest bezsensowne, ponieważ zmienna zawsze będzie zawierać NULL, drugie może rzeczywiście coś zawierać. Staje się to jeszcze bardziej interesujące, jeśli umieścimy wywołania funkcji w trybie warunkowym.

<?php

if (($foo1 = return_never())) {
    // Dead code
    var_dump($foo1);
}

if (($foo2 = return_sometimes())) {
    var_dump($foo2);
}

Jak widać, @return void ma swoje przypadki użycia i powinien być stosowany, jeśli ma zastosowanie.

Zauważ również, że będzie on częścią nadchodzącego standardu PHP PSR-5.^[1]

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

Od php 7.1, void jest poprawnym typem zwracanym i może być wymuszone na funkcji.

Ja bym zawsze dodała to na docbloku.

Kolejną korzyścią z jej napisania jest odróżnienie metod void od metod, które mogą zwracać cokolwiek, ale nie mają wpisu @return na docbloku przez zaniedbanie.

Oto jak Rozumiem i używam adnotacji PhpDocumentor:

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