Как использовать phpDoc с перегруженными методами?

Поскольку вы разрешаете аргументы переменной длины, я бы сделал это двумя способами.

Я бы просто перечислил разрешенные аргументы как параметры.

/**
 * @param mixed $arg1 ... description
 * @param mixed $arg2 ... description
 * @param mixed $arg3 ... description
 */
 public function __construct() {}

Или я бы просто дал объяснение с некоторыми примерами.

/**
 * Explanation of different expected argument combinations.
 */
public function __construct() {}

Другой альтернативой, поскольку только один из примеров имеет более одного аргумента, было бы просто определить аргументы в сигнатуре метода, сделав последние 2 необязательными. Как это:

/**
 * @param mixed $arg1 ...
 * @param int $arg2 ...
 * @param int $arg3 ...
 */
public function __construct($arg1, $arg2 = null, $arg3 = null) {}

Это просто моя точка зрения, но в первую очередь у вас не должно быть нескольких конструкторов - ваш конструктор будет полон лестниц if/else, что на самом деле не очень хорошая идея, особенно для чего-то легкого, такого как представление Цвет.

Я настоятельно рекомендую вам попробовать что-то вроде этого:

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

    ...
}

Теперь в потребительском коде вместо несколько загадочных и неоднозначных вызовов конструктора, подобных этим:

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

Вместо этого у вас может быть более разборчивый и семантический потребительский код, например:

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

Это, вероятно, имеет больше смысла для тех, кто читает потребительский код, он устраняет логику, необходимую для работы неоднозначного конструктора, и в качестве бонуса (если вы используете IDE, такую ​​​​как PhpStorm), вы можете пройти все свои проверки. Если вы используете генератор документации, это также гарантирует, что все параметры задокументированы по отдельности, а не объединены в словесное описание.

Обратите внимание, что я объявил конструктор protected - это личное предпочтение, но если я собираюсь иметь несколько статических фабричных методов, я предпочитаю видеть те, которые постоянно используются в потребительском коде, а не иногда видеть Color::fromRGB(...), а иногда new Color(...).

Я думаю, что лучше использовать аннотацию @method для класса/интерфейса, которая объявляет методы перегрузки. Этот вопрос меня тоже интересует.

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

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

Я не знаю элегантного способа сделать это с помощью phpDoc. Форматирование комментариев/API phpDoc основано на формате Javadoc. В Javadoc нет набора функций для поддержки этого, потому что в java, если вы хотите, чтобы метод имел переменное количество аргументов, вы повторно объявляете прототип метода для каждого варианта.

public double foo() {
}

public double foo(double my_param) {        
}

Итак, мое предпочтение производительности - сделать что-то вроде

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

но это может не очень хорошо сочетаться с различными инструментами автодокументации.

Согласно Хойлу способ сделать это можно найти в phpDoc. сайт.