在 PHP 文档块中包含 @param varname 仍然是合适的

Question

根据维基百科，@param docblock参数的格式是type [$varname] description其中$varname是可选的。这似乎得到了phpDocumentor项目的支持，该项目指出：

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

注意：从 0.4.1 开始，@param可以记录 phpdoc.de 样式，并带有可选的$paramname

那么，包括$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 中是否仍然可用。