How to use phpDoc with overloaded methods?

Just my point of view, but you should not have multiple constructors in the first place - your constructor is going to be full of if/else-ladders, which really isn't a good idea, especially for something lightweight like a representation of a Color.

I strongly encourage you to try something like this instead:

class Color{    protected function __construct($r, $g, $b)    { ... }    public static function fromHex($hex) {        return new Color(...);    }    public static function fromRGB($r, $g, $b) { ... }    public static function fromArray(array $rgb) { ... }    ...}

Now, in consumer code, instead of somewhat mysterious and ambiguous constructor calls like these:

$a = new Color(0,0,0);$b = new Color('#000000');

Instead you can have more legible and semantic consumer code, like this:

$a = Color::fromRGB(0,0,0);$b = Color::fromHex('#000000');

This probably makes more sense to somebody reading the consumer code, it eliminates the logic required to make the ambiguous constructor work, and as a bonus (if you're using an IDE such as PhpStorm) you can have all your inspections pass. If you're running a documentation generator, this also ensures that all the options are documented individually, rather than lumped together in a verbal description.

Note that I declared the constructor protected - this is a personal preference, but if I'm going to have multiple static factory-methods, I prefer to see those consistently used in consumer code, rather than sometimes seeing Color::fromRGB(...) and other times new Color(...).

I think that is better to use @method annotation for class/interface, which declares overloading methods. This question is interesting for me too.

 /**  * @method void setValue(int $value)  * @method void setValue(string $value)  * @method void setValue(string $value, int $startFrom)  */ class Example {     public function setValue($arg1, $arg2)     {        // ...     } }

See http://phpdoc.org/docs/latest/references/phpdoc/tags/method.html

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