0

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) { ... }
Xeoncross
  • 55,620
  • 80
  • 262
  • 364
  • I would go with the actual software's (phpDocumenter) documentation over wikipedias. – dm03514 Jun 05 '12 at 16:59
  • Well, while don't see any conflict between them, phpDocumentor is based on the docblock standard, so wikipedia is probably more important than the phpDoc implementation. – Xeoncross Jun 05 '12 at 17:03

1 Answers1

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.

ashnazg
  • 6,558
  • 2
  • 32
  • 39
  • [Seems you are right](http://www.phpdoc.org/docs/latest/for-users/tags/param.html) as `"Note phpDocumentor supports @param tags which omit the name, this is NOT RECOMMENDED but provided for compatibility with existing projects."` – Xeoncross Jun 05 '12 at 19:17