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

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

Answer 3

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 4

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.