PHPDoc for variable-length arrays of arguments.

Question

Is there a syntax for documenting functions which take a single configuration array, rather than individual parameters?

I'm thinking specifically of CodeIgniter-style libraries, which use a mechanism similar to this:

<?php

//
// Library definition
//

class MyLibrary {
  var $foo;
  var $bar;
  var $baz;
  // ... and many more vars...


  /* Following is how CodeIgniter documents their built-in libraries,
   * which is mostly useless.  AFAIK they should be specifying a name
   * and description for their @param (which they don't) and omitting
   * @return for constructors 
   */

  /** 
   * @access public
   * @param array
   * @return void
   */
  function MyLibrary($config = array()) {
    foreach ($config as $key => $value) {
      $this->$key = $value;
    }
  }
}

//
// Library usage:
//

// Iniitialize our configuration parameters
$config['foo'] = 'test';
$config['bar'] = 4;
$config['baz'] = array('x', 'y', 'z');

$x = new MyLibrary($config);

?>

So my question is, is there some supprted way of documenting the configuration array beyond just the purely textual description? Actually specifying a proper "@param [type] [name] [desc]" that allows PHPDoc to parse out useful values?

UPDATE

As an aside, CodeIgniter really does just overwrite it's own values with those passed in via the $config array as above, effectively allowing you to clobber private members. I'm not a fan, but I'm stuck with it.

Answer 1

I've never seen any "good" way of documenting this -- and I've never seen anything that could be used by IDEs (such as Eclipse PDT) for parameters hinting either :-(

I would have said "do like your framework does", but as you said, what it does, here, is not quite good enough...

Maybe a quick/sort list of possible keys might be better than nothing, though ; a bit like this :

@param array $config [key1=>int, otherKey=>string]

Not sure how it would be interpreted by phpDocumentor or an IDE... But might be worth a try ?

This is, btw, one reason for which I tend to avoid that kind of way of passing parameters -- at least when there are not too many (optionnal) parameters to a method.

Answer 2

A text description, to whatever degree of completeness you want, is really your only option. You can make it as legible as you want, but code analysis tools (phpDocumentor, IDE support) has no way to know how your $array is actually structured at runtime.

I agree with the many commenters that writing code this way exchanges coding convenience for code legibility.

Answer 3

The correct array @param notation for arrays is as specified in PHPlint

Example:

 /**
 * Does stuff
 *
 * @param array[int|string]float $bar
 * @param array[int|string]array[string]Object $multidim
 *
 * @return array[int]string
 */
public function foo(array $bar, array $multidim)
{
    // do stuff here

    return array('foo', 'bar', 'baz');
}