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

это действительно необходимо сделать что-то вроде этого:

/**
 * ...
 * 
 * @return void
 */

У меня есть довольно много методов, которые не возвращают значение, и это кажется лишним поставить что-то подобное в комментарии. Будет ли это считаться дурным тоном оставить его?

71
php phpdoc return-value

5 ответов

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

лично я бы оставил его.

редактировать
Я поправляюсь. Немного погуглив,Википедия страницы говорит:

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

phpdoc.org сайт говорит:

@return описание типа данных
@return datatype1 / описание datatype2

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

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

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

80

согласно 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 (архивные страницы).

42

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

используя @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. Но возвращаемое значение бесполезно для вызывающего, так как оно ничего не говорит о том, что сделала функция. IDEs может использовать документированную информацию @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/

13

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

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

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

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();
}
2