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

согласно phpDocumentor, @return void является допустимым:

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

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

например:

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

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

Источник: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 to укажите разработчику, что используются возвращаемые значения, которые не служат никакой цели.

<?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/

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

Я бы всегда добавить его в docblock.

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

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