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.

Pascal MARTIN · Accepted Answer · 2011-11-14 16:32:57Z

11

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.

edited Nov 14, 2011 at 16:32

user212218

answered Jan 5, 2010 at 21:12

Pascal MARTIN

402k82 gold badges665 silver badges666 bronze badges

Sign up to request clarification or add additional context in comments.

3 Comments

user229044 Over a year ago

I'd avoid it if I could, unfortunatly CodeIgniter's conventions require this sort of sloppy config array usage rather than, oh say, regular old parameters.

Pascal MARTIN Over a year ago

@meagar : yeah, I guessed/understood that, but couldn't resist ^^ (and this might be helpful if someone else, some day, arrives on this question/answer)

Gordon Over a year ago

That's similar to how I do it. PHPDoc will take the list and add it to the documentation just like any other string, so it is better than nothing. PDT cannot make sense of it though. It will just know it is an array.

Structed · Accepted Answer · 2013-05-24 09:18:31Z

4

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');
}

edited May 24, 2013 at 9:18

answered Oct 21, 2010 at 13:47

Structed

591 silver badge4 bronze badges

2 Comments

user229044 Over a year ago

This doesn't address my question about documenting which specific array keys are used as optional named parameters.

Structed Over a year ago

Yeah, not directly. But I wanted to point out the lint notation, which would help you in documenting such a config array in a useful manner. I edited my answer accordingly.

Moazzam Khan · Accepted Answer · 2011-08-29 22:34:50Z

2

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

answered Aug 29, 2011 at 22:34

Moazzam Khan

211 bronze badge

1 Comment

cweiske Over a year ago

Netbeans 7.0.1 with PHP plugin 1.17.1 does not interpret that, neither does Eclipse 3.7.2 with PDT 3.1.1

Jason Grimes · Accepted Answer · 2012-06-01 19:19:48Z

1

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.

answered Jun 1, 2012 at 19:19

Jason Grimes

1162 bronze badges

Comments

cweiske · Accepted Answer · 2012-10-04 08:14:14Z

1

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

answered Oct 4, 2012 at 8:14

cweiske

31.4k15 gold badges150 silver badges206 bronze badges

Comments

user229044 · Accepted Answer · 2011-05-20 13:32:23Z

0

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.

edited May 20, 2011 at 13:32

user229044♦

241k41 gold badges346 silver badges350 bronze badges

answered Jan 6, 2010 at 21:00

ashnazg

6,7282 gold badges34 silver badges40 bronze badges

Comments

Odalrick · Accepted Answer · 2012-10-15 09:52:32Z

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.

Collectives™ on Stack Overflow

PHPDoc for variable-length arrays of arguments

7 Answers 7

3 Comments

2 Comments

1 Comment

Comments

Comments

Comments

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

7 Answers 7

3 Comments

2 Comments

1 Comment

Comments

Comments

Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related