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.
void
i umieszcza go w podpisie metody w dokumentacji.return
wartości, znacznik @return MOŻE zostać tutaj pominięty, w takim przypadku zakłada się @return void."@return void
.void
jest 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.Według phpDocumentor, @return void jest ważne:
http://www.phpdoc.org/docs/latest/guides/types.html#keywords
Źródło: http://www.phpdoc.org/docs/latest/for-users/phpdoc/types.html ( strona archiwalna ).
źródło
Muszę zmienić odpowiedź z powodu czegoś, czego ostatnio się nauczyłem.
Używanie
@return void
zamiast@return null
ma 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 zwracaNULL
. 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 void
ma 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/
źródło
null
. Czy mam rację? Myślę, że w takim przypadku@returns void
jest to najlepsza opcja.NULL
jeśli nie zwrócisz niczego innego. Funkcja, która używaexit()
lub coś podobnego, nadal zwraca,NULL
ale nie otrzymasz jej, ponieważ PHP bezpośrednio przechodzi do fazy zamykania, ignorując Twój kod.finally
bloki 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. :)NULL
[…]”. Wydaje mi się, że możemy porównaćexit
z 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ą (npregister_shutdown
,__destruct
).@returns void
do 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.Od php 7.1
void
jest 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
void
metod od metod, które mogą zwracać cokolwiek, ale nie mają@return
wpisu w docblock przez zaniedbanie.źródło
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(); }
źródło
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
Oczywiście użycie @return przynajmniej wskazuje, że funkcja zwraca
źródło