Is is still proper to include the @param varname in a PHP docblock? [closed]

Question

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 3 years ago.

Improve this question

According to wikipedia the format for @param docblock parameters is type [$varname] description where $varname is optional. This seems to be backed by the phpDocumentor project which states:

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

NOTE: as of 0.4.1, @param can document phpdoc.de-style, with optional $paramname

So is it still proper form to include the $paramname or should it be left out?

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

Answer 1

More "proper form" would be to include $paramname. It ensures zero ambiguity in matching the @param line with its matching argument in the function signature. It is very likely listed as "optional" only as as old backwards-compatibility issue with "phpdoc.de style". I doubt that this optional handling remains available in phpDocumentor2.