PHPDoc: @return void необходимо?

Если это даёт понять документацию, то оставьте его, но это не является абсолютно необходимым. Это совершенно субъективное решение.

Лично я оставил бы это.

РЕДАКТИРОВАТЬ
Я стою исправлено. После небольшой поисковой системы на странице википедии говорится:

@return [описание типа] Этот тег не должен использоваться для конструкторов или методов, определенных с типом возвращаемого значения void.

На веб-сайте phpdoc.org говорится:

Описание datatype @return
@return datatype1 | описание datatype2

Тег @return используется для документирования возвращаемого значения функций или методов. @returns является псевдонимом для @return для поддержки форматов тегов других автоматических документов

Тип данных должен быть допустимым типом PHP (int, string, bool и т. Д.), Именем класса для возвращаемого типа объекта или просто «смешанным». Если вы хотите явно показать несколько возможных типов возвращаемых данных, перечислите их без ограничений (например, «@return int | string»). Если имя класса используется как тип данных в теге @return, phpDocumentor автоматически создаст ссылку на документацию этого класса. Кроме того, если функция возвращает несколько возможных значений, отделите их, используя | character и phpDocumentor будут анализировать любые имена классов в возвращаемом значении. phpDocumentor отобразит необязательное описание без изменений.

Sooo … Исходя из этого, я бы сказал, оставьте пустоту. По крайней мере, это нестандартно.

Согласно phpDocumentor, действует @return void:

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

… этот тип обычно используется только при определении возвращаемого типа метода или функции. Основное определение состоит в том, что элемент, указанный этим типом, не содержит значения, и пользователь не должен полагаться на какое-либо полученное значение.

Например:

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

В приведенном выше примере не указан оператор возврата, и, следовательно, возвращаемое значение не определено.

Источник: http://www.phpdoc.org/docs/latest/for-users/phpdoc/types.html ( архивная страница ).

Я должен отредактировать свой ответ из-за того, что я узнал недавно.

Использование @return void вместо @return null имеет очень особое значение, рассмотрим следующие два примера кода PHP.

 <?php /** * @return void */ function return_never() { echo "foo"; } /** * @return null|string */ function return_sometimes() { if ($this->condition()) { return "foo"; } } 

В первом примере PHP фактически вернет NULL , так как PHP всегда возвращает NULL . Но возвращаемое значение бесполезно для вызывающего, поскольку оно ничего не говорит о том, что сделала функция. IDE могут использовать документальную информацию @return void чтобы указать разработчику, что используются значения возврата, которые не имеют никакой цели.

 <?php $foo1 = return_never(); $foo2 = return_sometimes(); 

Первый вызов бессмыслен, так как переменная всегда будет содержать NULL , вторая может фактически что-то содержать. Это становится еще более интересным, если мы переместим вызовы функций в условные.

 <?php if (($foo1 = return_never())) { // Dead code var_dump($foo1); } if (($foo2 = return_sometimes())) { var_dump($foo2); } 

Как вы можете видеть, @return void имеет свои варианты использования и должен использоваться, если применимо.

Также обратите внимание, что это будет частью предстоящего стандарта PHP PSR-5. ^[1]

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

Вот как я понимаю и использую аннотации 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(); } 

Начиная с php 7.1, void является допустимым типом возврата и может быть применен к функции.

Я всегда добавлял его в док-блок.

Еще одно преимущество его написания – отличать методы void от методов, которые могут возвращать что-либо, но не имеют записи @return на docblock по небрежности.