web-dev-qa-db-ja.com

PHP7を使用する場合、PHPDocを使用してメソッドを文書化する必要がありますか？

PHP7では、メソッドが特定のパラメータータイプと結果タイプを設定するときに、それらをPHPDocに再度文書化する必要がありますか？

以来

function foo(string $text): bool
{
    return true;
}

と同等です

/**
 * @param string $text
 * @return bool
 */
function foo($text) {
    return true;
}

これらの情報を複製する必要がありますか？

/**
 * @param string $text
 * @return bool
 */
function foo(string $text): bool
{
    return true;
}

編集：PHPDocを使用してコードのドキュメントを生成するのではなく、PHPStormを使用して、私と同僚のメソッドの一貫性を維持します。

phpphp-7phpdoc
16
Marc Brillault

Docblockは、コーダーが関数の機能を説明するために使用できるものです。これは単なるコメントであるため、PHPパーサーによって無視されます。docblockを上に配置することをお勧めします。すべての関数とメソッド。誰か（またはあなた）がコードを読むと、関数の機能を簡単に確認できるためです。

A IDEは通常、オートコンプリートのためにdocblockを使用しますが、ブロックがコードと一致しない場合、docblockはstringおよび_:bool_によってオーバーライドされます。

しかしながら

_function foo(string $text): bool
{
    return true;
}
_

と同等ではありません

_/**
 * @param string $text
 * @return bool
 */
function foo($text) {
    return true;
}
_

最初の例の_:bool_は、foo()がtrueまたはfalseのいずれか、その他を返すことを強制し、PHPは試行しますその型に戻り値をキャストするか、致命的なエラーをスローします。これは、_$text_のtypehint stringと同じです。最初のパラメータは文字列型の値である必要があります。それ以外の場合はPHPはそれを文字列にキャストしようとすると、致命的なエラーがスローされます

_@return bool_および_@param string_は何も強制せず、期待収益がtrueまたはfalseのいずれかであるとだけ言っています。

次の例を見てください。

_function foo(string $a) :bool
{
    var_dump($a); // string '10'
    return "string";
}

var_dump(foo(10)); // bool true
_

問題はありません。PHPは_10_を文字列にキャストでき、_"string"_はtrueですが次の問題があります。

_function foo(PDO $a) :bool 
{
    var_dump($a);
    return "string";
}

var_dump(foo(10)); // fatal error, 10 is not PDO and can not be cast to PDO
_

Docblockを使用すると、最後の1つが機能します（おそらく、PDOオブジェクトで何かをしようとしているため、他の問題が発生する可能性があります）

注：PHPは、混合型タイプヒント（つまり、文字列|配列）をまだサポートしていません。これは、docblockで指定することによって実行する必要があります。

編集：
@ inwerpselがコメントで指摘したように、docblockはPHPパーサーが正しくありません。docblockは実行時に ReflectionClass 。

19
Jelmergu