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?

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 why I tend to avoid that kind of way of passing parameters — at least when there are not too many (optional) parameters to a method.