web-dev-qa-db-ja.com

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

このようなことは本当に必要ですか：

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

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

phpreturn-valuephpdoc
76
Richie Marquez

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

個人的には、私はそれを除外します。

[〜＃〜] edit [〜＃〜]
私は修正しました。少しグーグルで調べた後、 wikipediaページ はこう言います：

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

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

@returnデータ型の説明
@ return datatype1 | datatype2の説明

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

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

すっごく...それに基づいて、私はボイドを除外すると言うでしょう。少なくとも非標準です。

88
Jonathan Fingland

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

45
tivnet

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

@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";
    }
}

最初の例では、PHPは実際にNULLを返します。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にはユースケースがあり、該当する場合は使用する必要があります。

また、今後のPHP PSR-5標準の一部になる予定です。[1]

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

13
Fleshgrinder

Php 7.1の時点で、 voidは有効な戻り値の型 およびを関数に適用できます。

私はalwaysdocblockに追加します。

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

5
Dimitris Baltas

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
Dejv