How to use phpDoc with overloaded methods?

Question

Let's say I have a PHP class called Color, it's constructor accepts various params.

// hex color
$myColor = new Color('#FF008C');

// rgb channels
$myColor = new Color(253,15,82);

// array of rgb channels
$myColor = new Color(array(253,15,82));

// X11 color name
$myColor = new Color('lightGreen');

My question is:

How should I use phpDoc to create API documentation for constructor and other methods like this?

How to use phpDoc with overloaded methods?

class Color {

 /**
  * Constructor
  * what should be here?
  */
 public function __construct() {
  /* CODE */
 }

}

Answer 1

Because you allow variable length arguments there are two ways I would do this.

I would simply list the allowed arguments are parameters.

/**
 * @param mixed $arg1 ... description
 * @param mixed $arg2 ... description
 * @param mixed $arg3 ... description
 */
 public function __construct() {}

Or I would simply provide an explanation with some examples.

/**
 * Explanation of different expected argument combinations.
 */
public function __construct() {}

Another alternative, since only one of the examples has more than one argument, would be to simply define the arguments in the method signature making the last 2 optional. Like this:

/**
 * @param mixed $arg1 ...
 * @param int $arg2 ...
 * @param int $arg3 ...
 */
public function __construct($arg1, $arg2 = null, $arg3 = null) {}

Answer 2

I know of no elegant way to do this with phpDoc. The phpDoc comment/api formatting is based on a the Javadoc format. Javadoc doesn't have a feature set to support this because in java, if you want a method to have a variable number of arguments you re-declare the method prototype for each variation.

public double foo() {
}

public double foo(double my_param) {        
}

So, my performance preference is to do something like

/**
 * My General description
 * 
 * Here explain what each argument combination can do
 * @param mixed $arg1 can be array, string, hex as string, or int 
 * @param int $arg2 if arg1 is int, then this is etc, otherwise optional 
 * @param int $arg3 if ar1 is int, then this is etc, otherwise optional
 */

but this may not play nice with the various auto-documentation tools.

The according to Hoyle way to accomplish this can be found at the phpDoc site.

Answer 3

@param string ex. "#FF008C"|mixed ex. array(0..255,0..255,0..255)|string Named color. ex. "lightGreen"|int $r, int $g, int $b 0..255 color code

It's ridiculously long,in this case, but refer to lines 31-33 in the @param docs for phpDoc.