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

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

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

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

73 голоса | спросил Richie Marquez 14 Jam1000000amThu, 14 Jan 2010 04:09:14 +030010 2010, 04:09:14

5 ответов


0

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

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

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

  

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

На сайте phpdoc.org написано:

  

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

     

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

     

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

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

ответил Jonathan Fingland 14 Jam1000000amThu, 14 Jan 2010 04:11:36 +030010 2010, 04:11:36
0

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

http://www.phpdoc.org/docs/latest/руководства /types.html # ключевых слов

  

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

     

Например:

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

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

Источник: http://www.phpdoc.org/docs /latest /для пользователей /phpdoc /types.html ( заархивированная страница ).

ответил tivnet 30 thEurope/Moscowp30Europe/Moscow09bEurope/MoscowMon, 30 Sep 2013 17:14:00 +0400 2013, 17:14:00
0

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

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

ответил Fleshgrinder 24 PM00000090000003931 2013, 21:26:39
0

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

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

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

ответил Dimitris Baltas 11 thEurope/Moscowp30Europe/Moscow09bEurope/MoscowMon, 11 Sep 2017 20:10:05 +0300 2017, 20:10:05
0

Вот как я понимаю и использую аннотации 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();
}
ответил Dejv 13 FebruaryEurope/MoscowbSat, 13 Feb 2016 18:43:17 +0300000000pmSat, 13 Feb 2016 18:43:17 +030016 2016, 18:43:17

Похожие вопросы

Популярные теги

security × 330linux × 316macos × 2827 × 268performance × 244command-line × 241sql-server × 235joomla-3.x × 222java × 189c++ × 186windows × 180cisco × 168bash × 158c# × 142gmail × 139arduino-uno × 139javascript × 134ssh × 133seo × 132mysql × 132