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

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

Answer 2

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(...).