How to use phpDoc with overloaded methods?

documentation-generation, overloading, php, phpdoc

Solution

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

Problem

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 */ } } ```

Original source