Cómo utilizar phpDoc con métodos sobrecargados?

Question

Vamos a decir que tengo una clase PHP llamado Color , que es constructor acepta diferentes parametros.

// 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');

¿Cómo debo usar phpDoc para crear documentación de la API de constructor y otros métodos como este?

Como utilizar phpDoc con métodos sobrecargados?

class Color {

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

}

Answer 1

Debido a que usted permite que los argumentos de longitud variable hay dos maneras Me gustaría hacer esto.

Me limitaré a enumerar los argumentos permitidos son parámetros.

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

O yo simplemente proporcionar una explicación con algunos ejemplos.

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

Otra alternativa, ya que sólo uno de los ejemplos tiene más de un argumento, sería simplemente definir los argumentos en la firma del método que hace el último 2 opcional. De esta manera:

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

Answer 2

Sólo mi punto de vista, pero que no debería tener varios constructores en el primer lugar - el constructor va a estar lleno de if / else de tijera, que realmente no es una buena idea, especialmente para algo como un peso ligero representación de un color.

Los animo a intentar algo como esto en su lugar:

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

    ...
}

Ahora, en el código de consumo, en lugar de constructor de algo misterioso y ambiguo llamadas como los siguientes:

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

En su lugar puede tener el código de consumo más legibles y semántica, así:

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

Esto probablemente tiene más sentido para alguien que lee el código del consumidor, que elimina la lógica necesaria para hacer funcionar el constructor ambigua, y como un bono (si estás usando un IDE como PhpStorm) puede tener pasan todas sus inspecciones . Si se está utilizando un generador de documentación, esto también se asegura de que todas las opciones están documentados de forma individual, en lugar de agrupados en una descripción verbal.

Tenga en cuenta que declaré el protected constructor - esto es una preferencia personal, pero si voy a tener múltiples factoría métodos estáticos, prefiero ver a los que se usan constantemente en el código de consumo, en lugar de ver a veces y otras veces Color::fromRGB(...) new Color(...).

Answer 3

Creo que es mejor usar la anotación @method para la clase / interfaz, que declara la sobrecarga de métodos. Esta pregunta es interesante para mí también.

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

Answer 4

No conozco ninguna manera elegante de hacer esto con phpDoc. El formato comentario phpDoc / API se basa en un href="http://java.sun.com/j2se/javadoc/" la rel="nofollow noreferrer"> formato

public double foo() {
}

public double foo(double my_param) {        
}

Por lo tanto, mi preferencia rendimiento es hacer algo como

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

pero esto puede no jugar bien con las diversas herramientas de auto-documentación.

El acuerdo con manera Hoyle de lograr esto se puede encontrar en la sitio phpDoc .