PHPDoc: @return void konieczne?

Czy naprawdę trzeba zrobić coś takiego:

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

Mam kilka metod, które nie mają wartości zwracanej i umieszczanie czegoś takiego w komentarzu wydaje się naprawdę zbędne. Czy pominięcie go byłoby uważane za zły sposób?

Jeśli jest to jasne dla dokumentacji, zostaw to, ale nie jest to bezwzględnie konieczne. To całkowicie subiektywna decyzja.

Osobiście zostawiłbym to.

EDYCJA
Stoję poprawione. Po krótkiej wygooglowaniu strona wikipedii mówi:

@return [opis typu] Tego znacznika nie należy używać w przypadku konstruktorów lub metod zdefiniowanych z zwracanym typem void.

Witryna phpdoc.org mówi:

@return datatype description
@return datatype1 | datatype2 description

Znacznik @return służy do dokumentowania wartości zwracanej funkcji lub metod. @returns to alias dla @return do obsługi formatów tagów innych automatycznych dokumentatorów

Typ danych powinien być prawidłowym typem PHP (int, string, bool itp.), Nazwą klasy dla typu zwracanego obiektu lub po prostu „mieszanym”. Jeśli chcesz jawnie pokazać wiele możliwych typów zwracanych, podaj je rozdzielone pionową kreską bez spacji (np. „@Return int | string”). Jeśli nazwa klasy jest używana jako typ danych w tagu @return, phpDocumentor automatycznie utworzy łącze do dokumentacji tej klasy. Ponadto, jeśli funkcja zwraca wiele możliwych wartości, oddziel je za pomocą | znak, a phpDocumentor przeanalizuje wszystkie nazwy klas w zwracanej wartości. phpDocumentor wyświetli opcjonalny opis niezmodyfikowany.

Sooo ... Opierając się na tym, powiedziałbym, że pomiń pustkę. Przynajmniej jest to niestandardowe.

Według phpDocumentor, @return void jest ważne:

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

... ten typ jest powszechnie używany tylko podczas definiowania zwracanego typu metody lub funkcji. Podstawowa definicja jest taka, że ​​element wskazany tym typem nie zawiera wartości i użytkownik nie powinien polegać na żadnej pobranej wartości.

Na przykład:

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

W powyższym przykładzie nie określono żadnej instrukcji return, a zatem nie określono wartości zwracanej.

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

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

Używanie @return voidzamiast @return nullma bardzo szczególne znaczenie, rozważ dwa poniższe 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 faktycznie zwróci NULL, ponieważ PHP zawsze zwraca NULL. Ale zwracana wartość jest bezużyteczna dla wywołującego, ponieważ nie mówi nic o tym, co zrobiła funkcja. IDE mogą korzystać z udokumentowanych informacji z@return void aby wskazać deweloperowi, że używane są wartości zwracane, które nie służą żadnemu celowi.

<?php

$foo1 = return_never();

$foo2 = return_sometimes();

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

<?php

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

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

Jak widać, @return voidma swoje przypadki użycia i powinien być używany, jeśli dotyczy.

Zwróć też uwagę, że będzie to część nadchodzącego standardu PHP PSR-5.^[1]

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

Od php 7.1 voidjest prawidłowym typem zwracania i może być wymuszony na funkcji.

Ja zawsze dodać go na bloku dokumentacyjnym.

Kolejną zaletą pisania tego jest odróżnienie voidmetod od metod, które mogą zwracać cokolwiek, ale nie mają @returnwpisu w docblock 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();
}

Osobiście uważam, że główną rzeczą, której w tym brakuje, jest to, że dokumentowanie funkcji zwraca w ogóle ważne. Obecnie standardy nie mają żadnej dokumentacji dla funkcji, które nigdy nie zwracają ... stąd zwrot void jest sposobem na powiedzenie tak, ta funkcja faktycznie zwraca.

Rozważ ten blok kodu

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

Oczywiście użycie @return przynajmniej wskazuje, że funkcja zwraca