PHPDoc：@return voidが必要ですか？

Question 1

このようなことをする必要が本当にありますか？

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

戻り値のないメソッドがかなりありますが、コメントにこのようなものを入れるのは本当に冗長なようです。それを省くことは悪い形と見なされますか？

Question 2

ドキュメントで明確になっている場合は、そのままにしておきますが、厳密には必要ありません。それは完全に主観的な決定です。

個人的には省略します。

編集
私は修正されたままです。少しグーグルした後、ウィキペディアのページには次のように書かれています。

@return [タイプの説明]このタグは、voidの戻り値の型で定義されたコンストラクターまたはメソッドには使用しないでください。

phpdoc.orgのWebサイトには次のように書かれています。

@returnデータ型の説明
@returnデータ型1 |データ型2の説明

@returnタグは、関数またはメソッドの戻り値を文書化するために使用されます。@returnsは、他の自動ドキュメンターのタグ形式をサポートするための@returnのエイリアスです。

データ型は、有効なPHP型（int、string、boolなど）、返されるオブジェクトの型のクラス名、または単に「混合」である必要があります。複数の可能な戻り値の型を明示的に表示する場合は、スペースなしでパイプ区切りでリストします（例： "@ return int | string"）。@returnタグのデータ型としてクラス名が使用されている場合、phpDocumentorはそのクラスのドキュメントへのリンクを自動的に作成します。さらに、関数が複数の可能な値を返す場合は、|を使用してそれらを区切ります。文字、およびphpDocumentorは、戻り値のクラス名を解析します。phpDocumentorは、オプションの説明を変更せずに表示します。

すっごく...それに基づいて、私は空白を省くと言うでしょう。少なくとも、それは非標準です。

Question 3

phpDocumentorによると、@ returnvoidは有効です。

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（アーカイブページ）。

Question 4

最近学んだことがあるので、答えを編集する必要があります。

の@return void代わりに使用することは@return null非常に特別な意味を持ち、次の2つのPHPコードの例を検討してください。

<?php

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

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

最初の例NULLでは、PHPは常にを返すため、PHPは実際にはを返しますNULL。ただし、戻り値は、関数が何をしたかについては何も述べていないため、呼び出し元には役に立ちません。IDEは、の文書化された情報を@return void使用して、目的を果たさない戻り値が使用されていることを開発者に示すことができます。

<?php

$foo1 = return_never();

$foo2 = return_sometimes();

変数には常にが含まれるため、最初の呼び出しは無意味ですNULL。2番目の呼び出しには実際に何かが含まれている可能性があります。関数呼び出しを条件付きにすると、これはさらに興味深いものになります。

<?php

if (($foo1 = return_never())) {
    // Dead code
    var_dump($foo1);
}

if (($foo2 = return_sometimes())) {
    var_dump($foo2);
}

ご覧のとおり@return void、ユースケースがあり、該当する場合は使用する必要があります。

また、今後のPHPPSR-5標準の一部になることにも注意してください。^[1]

[1] http://www.php-fig.org/psr/

Question 5

php 7.1以降、voidは有効な戻り値の型であり、関数に適用できます。

私はいつもそれをdocblockに追加します。

それを書くことのもう一つの利点は、void何かを返すかもしれないが、@return過失によってdocblockにエントリを持たないメソッドからメソッドを区別することです。

Question 6

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

Question 7

個人的には、これに欠けている大きなことは、関数が返すことを文書化することが重要だということだと思います。現在、標準には、決して戻らない関数のドキュメントがありません。したがって、return 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の使用は、少なくとも関数が戻ることを示しています