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

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) {}