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

Ответ 1

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

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

ИЗМЕНИТЬ
Я стою исправлено. После небольшой поисковой системы, страница wikipedia говорит:

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

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

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

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

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

Sooo... Основываясь на этом, я бы сказал, оставьте пустоту. Это нестандартное, по крайней мере.

Ответ 2

В соответствии с 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 (заархивированная страница).

Ответ 3

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

Использование @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/

Ответ 4

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

Ответ 5

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

Я бы всегда добавлял его в docblock.

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