php - @param varname を PHP docblock に含めることはまだ適切ですか?

Question

ウィキペディアによると、 @paramdocblock パラメータtype [$varname] descriptionの形式$varnameはオプションです。これは、次のように述べている phpDocumentor プロジェクトによって裏付けられているようです。

@param datatype $paramname description
@param datatype1|datatype2 $paramname description

注: 0.4.1 以降、@param は、オプションの $paramname を使用して phpdoc.de-style を文書化できます。

では、$paramname を含めるのは適切な形式でしょうか、それとも省略すべきでしょうか?

/**
 * Have a foo!
 *
 * @param string $foo is a string
 * @param string This is another string
 * @return string
 */
function haveAFoo($foo, $bar) { ... }

Answer 1

より「適切な形式」は、$paramname を含めることです。これにより、@param 行と関数シグネチャ内の一致する引数を一致させる際のあいまいさがなくなります。「phpdoc.de スタイル」との古い後方互換性の問題としてのみ、「オプション」としてリストされている可能性が非常に高いです。このオプションの処理が phpDocumentor2 で引き続き使用できるとは思えません。