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

Чи справді потрібно робити щось подібне:

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

У мене є досить багато методів, які не мають поверненого значення, і здається справді зайвим додавати щось подібне до коментаря. Чи вважатимемо це поганою формою, якщо це не помітити?

Якщо це чітко пояснює документацію, залиште це, але це не є суворо необхідним. Це цілком суб’єктивне рішення.

Особисто я б це залишив поза увагою.

EDIT
Я стою виправлений. Трохи погугливши, на сторінці Вікіпедії сказано:

@return [опис типу] Цей тег не повинен використовуватися для конструкторів або методів, визначених з типом повернення void.

На веб-сайті phpdoc.org сказано:

@return datatype description
@return datatype1 | datatype2 description

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

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

Оооо ... Виходячи з цього, я б сказав, залишити порожнечу. Це принаймні нестандартно.

Відповідно до 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 ( архівна сторінка ).

Я повинен відредагувати свою відповідь через те, про що я дізнався нещодавно.

Використання @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/

Станом на php 7.1, voidє дійсним типом повернення і може бути застосовано до функції.

Я завжди додавав би це на блок-блок.

Ще однією перевагою його написання є диференціація voidметодів від методів, які можуть повертати що-небудь, але не мають @returnзаписів на блоці даних через недбалість.

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

Особисто я думаю, що найбільшого, чого не вистачає в цьому, є те, що документування функції, яку взагалі повертає, є важливим. В даний час стандарти не мають жодної документації щодо функцій, які ніколи не повертаються .... отже, повернення void - це спосіб сказати так, ця функція насправді повертає.

Розглянемо цей блок коду

<?php

/**
 * @return void
 */
function return_void() {
    echo "foo";
}

/**
 * @return null|string
 */
function return_sometimes() {
    if ($this->condition()) {
        return "foo";
    }
}

/**
* This function actually doesnt return at all - it kills the script
**/
function noreturn() {
     //do somthing then
     die(); //or exit()
}

Очевидно, що використання @return принаймні вказує на те, що функція повертається