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?

class Color {

    /**
     * Constructor
     * what should be here?
     */
    public function __construct() {
        /* CODE */
    }

}

score 18 · Answer 1 · answered Jun 28 '13 at 16:11

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

You are right. The solution with static factory-methods results in much clearer code. — Tom Pažourek, Aug 10 '13 at 09:35
This answer deserves much more kudos as it is promoting better programming practices. — kwah, Sep 09 '13 at 17:34
That said, I realise that it does not strictly answer the original (rather old) question. Personally I see it like explaining how to use a screwdriver to hammer in a nail by saying "why not just use a hammer?". — kwah, Sep 09 '13 at 17:41
I'm saying "the screwdriver is the wrong tool for hammering nails" - now even if that was not the answer you wanted, it is the correct answer, unless you're sadistically hell-bent on bending your nails and hammering yourself over the fingers. — mindplay.dk, Sep 09 '13 at 19:33

score 9 · Answer 2 · answered Feb 27 '14 at 12:20

9

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

answered Feb 27 '14 at 12:20

Roman Shamritskiy

753
10
12

I personally working oh the same stuff and i preferr to use your approach. It is clear, usefull and intellisense work really fine. I use __Call method in order to match the correct parameters and call private function or void in order to complete my logic. Howevere php developer should be take care to improve Overloading in order to provide a more robust way to use this type of implementation which is really usefull. In .NET (from where i come) it is a common practice overloading a method/function and it is a very powerefull stuff. – makemoney2010 Aug 05 '16 at 14:40
I tried this recently and my IDE (PhpStorm / IntelliJ IDEA) didn't like it; it showed a warning on the duplicate declarations, failed to highlight the syntax properly and refused to suggest the duplicate methods later on. – Christian Jul 22 '21 at 06:47

score 4 · Accepted Answer · answered Aug 28 '09 at 19:33

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

I will use the second solution, one param with description (that it's one to three params and various formats) and some @see tags to examples. — Tom Pažourek, Aug 29 '09 at 13:30
This is old, but just to offer an alternative for reference sake -- you could also just say `@param mixed $args ... Variable number of arguments representing blah blah` — Brian Lacy, Sep 28 '11 at 19:37

Alana Storm · Answer 4 · 2009-08-28T20:03:43.207

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.

How to use phpDoc with overloaded methods?

4 Answers4