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?

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.

Answer 2

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

You can use it to document a config array in a useful manner:

Example:

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

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

Answer 3

You can do this:

/**
 * @param array $param1
 * @param string $param1['hello']
 */
function hey($param1)
{
}

and netbeans will pick it up but phpdoc messes up the documentation

Answer 4

I always use <pre> tags in situations like this. Ex.:

/**
 * @param array $ops An array of options with the following keys:<pre>
 *     foo: (string) Some description...
 *     bar: (array) An array of bar data, with the following keys:
 *         boo: (string) ...
 *         far: (int) ...
 *     baz: (bool) ...
 * </pre>
 */

Most IDEs and documentation generators I have used seem to render this in a reasonable way, though of course they don't provide any type checking or inspection of the array parameters.

Answer 5

There is currently no "official" (as in 'supported by multiple tools') way to do this.

The PHP FIG is discussing it at the moment at https://groups.google.com/d/topic/php-fig/o4ko1XsGtAw/discussion

Answer 6

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) have 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 7

I've used classes.

<?php
class MyLibrary {
    var $foo;
    var $bar;
    var $baz;

    /**
     * @param MyLibraryConfig|null $config
     */
    function MyLibrary( $config = null ) {
        if ( isset( $config->foo ) ) {
            $this->foo = $config->foo;
        }
        if ( isset( $config->baz ) ) {
            $this->baz = $config->baz;
        }
        if ( isset( $config->bar ) ) {
            $this->bar = $config->bar;
        }
    }
}

/**
 * @property string $foo
 * @property int    $bar
 * @property array  $baz
 */
class MyLibraryConfig {
}

It works fairly well, main problem is that the code becomes littered with specific classes. They can be nested so parts of configuration can be reused.