PHPDoc: @return void konieczne?

81

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?

Richie Marquez
źródło

Odpowiedzi:

91

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.

Jonathan Fingland
źródło
Czy dodanie tego w ogóle coś robi? Wierzę w PHPDoc, jeśli nie dokumentujesz zwracanego typu, który automatycznie przyjmuje voidi umieszcza go w podpisie metody w dokumentacji.
Marc W
@Marc W: zobacz moją edycję. nie tylko nie jest to konieczne, ale nie powinno być używane.
Jonathan Fingland
2
Mogło się zmienić od 2010 roku, ale obecnie phpdoc.org mówi: "funkcje i metody bez returnwartości, znacznik @return MOŻE zostać tutaj pominięty, w takim przypadku zakłada się @return void."
TFennis,
@TFennis Thanks. Zostawię poprzedni cytat bez zmian, ale wygląda na to, że phpdoc jest po prostu bardziej tolerancyjny wobec liczby programistów, którzy go używali. Zauważyłem, że strona wikipedii mówi teraz [potrzebne cytowanie] dla stwierdzenia o unikaniu @return void.
Jonathan Fingland
Z mojego punktu widzenia ta odpowiedź jest nieaktualna. Typ voidjest poprawnym typem zwracanym od PHP 7.1, a jako punkty @tivnet w poniższej odpowiedzi jest również prawidłowym typem dla phpDocs według phpDocumentor.
Ernesto Allely
50

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 ).

tivnet
źródło
4
W tym miejscu zwracam uwagę, że „to jest poprawna odpowiedź”. :)
Typo
3
Prawidłowa odpowiedź powinna zostać zmieniona na to.
BadHorsie,
4
Rzeczywiście, byłaby to najlepsza odpowiedź tutaj. Jest to również część nadchodzącego standardu PSR-5. Wybrałbym
znak
15

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/

Fleshgrinder
źródło
Słuszna uwaga, ale jeśli funkcja kończy działanie, oznacza to, że nie zwraca null. Czy mam rację? Myślę, że w takim przypadku @returns voidjest to najlepsza opcja.
Tamás Barta
Funkcja zawsze zwróci, NULLjeśli nie zwrócisz niczego innego. Funkcja, która używa exit()lub coś podobnego, nadal zwraca, NULLale nie otrzymasz jej, ponieważ PHP bezpośrednio przechodzi do fazy zamykania, ignorując Twój kod.
Fleshgrinder,
Ciekawy. Przypuszczałbym, że jeśli to, co mówisz, jest prawdą, finallybloki biegną, kiedy dzwonię exit. Nie jest to bezpośrednia korelacja między nimi, ale nie wydaje się to właściwe. Dzięki za oświecenie mnie. :)
Tamás Barta
Lepsze sformułowanie brzmiałoby: „[…] nadal wróci NULL[…]”. Wydaje mi się, że możemy porównać exitz goto, po prostu mówiąc PHP, aby przestał wykonywać bieżący kod i bezpośrednio przeskoczył do fazy zamykania, ignorując dowolny kod od tego momentu (w ten sposób goto w bardziej zewnętrznym zakresie [globalnym] niż jakakolwiek bieżąca funkcja jest zagnieżdżona) . Bloku finally nie zostanie wykonany, ale wiele innych funkcji są (np register_shutdown, __destruct).
Fleshgrinder
To brzmi bardziej sensownie i tak właśnie myślałem na początku. Postanowiłem też użyć @returns voiddo wskazania, że ​​funkcja przerywa wykonanie całego skryptu, na przykład przy przekierowaniu HTTP. Nadal lepiej byłoby użyć do wskazania, że ​​funkcja nie jest zaprojektowana do zwracania czegokolwiek.
Tamás Barta
7

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.

Dimitris Baltas
źródło
3

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();
}
Dejv
źródło
1

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

Narrim
źródło