PHPDoc: необходимо возвращать пустоту? - PullRequest
Новая
       13

PHPDoc: необходимо возвращать пустоту?

75 голосов
/ 14 января 2010

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

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

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

Ответы [ 5 ]

87 голосов
/ 14 января 2010

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

Лично я бы это исключил.

EDIT
Я стою исправлено. После небольшого поиска на странице википедии написано:

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

Сайт phpdoc.org сообщает:

@ возвращение описания типа данных
@return datatype1 | описание datatype2

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

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

Оооо ... Исходя из этого, я бы сказал, пропустите пустоту. Это как минимум нестандартно.

45 голосов
/ 30 сентября 2013

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

13 голосов
/ 24 августа 2013

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

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

5 голосов
/ 11 сентября 2017

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

Я бы всегда добавил его в докблок.

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

2 голосов
/ 13 февраля 2016

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