I found this code snippet which shows how array based parameters should be documented with PHPDoc (in ZF projects). The topic came up because I’m always nagging about those magic functions and magic properties in ZF and how poorly they are documented. It seems we’ve been neglecting adding PHPDoc tags a bit because PHPDoc does have support to document magic methods and magic class properties:

@method Magic Properties

@property Magic Methods

/**
* $args may contain the following keys:
* - var1:
* - var2:
*
* @param array @args
* @return void
*/

Items prefixed with a ‘- ‘ will be treated as bullets by phpDocumentor.

source: zend framework community

I’m currently piloting PhpStorm because I had some issues with Zend Studio, it’s interesting to notice that a phpdoc line like:

/*
 * @return Foo[]
 */
function getList() {
   $f = array();
   $f[] = new Foo();
   ...
   return $f;
}

triggers auto-completion in PhpStorm when looping over the return value like:

$list = $this->getList();
foreach($list as $l) {
    $l->(starts auto-completion ...)
}