Come utilizzare phpDoc con metodi sovraccaricati?

Question

Diciamo che ho una classe PHP chiamata Colore, il costruttore accetta vari parametri.

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

Come devo usare PHPDoc per creare documentazione API per costruttore e altri metodi come questo?

Come utilizzare phpDoc con metodi sovraccaricati?

class Color { 

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

} 

Answer 1

Poiché si accettano argomenti di lunghezza variabile, ci sono due modi per farlo.

Vorrei semplicemente elencare gli argomenti consentiti come parametri.

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

Oppure vorrei semplicemente fornire una spiegazione con alcuni esempi.

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

Un'altra alternativa, dal momento che solo uno degli esempi ha più di un argomento, sarebbe definire semplicemente gli argomenti nella firma del metodo procede all'ultimo 2 opzionale. Come questo:

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

Answer 2

Non conosco nessun modo elegante per fare questo con PHPDoc. La formattazione di commenti/api di phpDoc si basa sul formato Javadoc. Javadoc non ha un set di funzionalità per supportare questo perché in Java, se si desidera che un metodo abbia un numero variabile di argomenti, si dichiara nuovamente il prototipo del metodo per ciascuna variante.

public double foo() { 
} 

public double foo(double my_param) {   
} 

Quindi, la mia preferenza prestazioni è quello di fare qualcosa di simile

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

ma questo non può giocare piacevole con i vari strumenti di auto-documentazione.

Il modo in cui Hoyle per farlo è reperibile allo phpDoc site.

Answer 3

Solo il mio punto di vista, ma non dovresti avere più costruttori in primo luogo - il tuo costruttore sarà pieno di if/else-ladders, che in realtà non è una buona idea, soprattutto per qualcosa di leggero come una rappresentazione di un colore.

ho vivamente di provare qualcosa di simile, invece:

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

    ... 
} 

Ora, nel codice del consumo, invece di chiamate costruttore un po 'misterioso e ambiguo come questi:

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

Invece si può avere codice consumatore più leggibile e semantico, come questo:

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

Questo probabilmente ha più senso per qualcuno che legge il codice del consumatore, elimina la logica necessaria per far funzionare il costruttore ambiguo e come bonus (se usi un IDE come PhpStorm) puoi passare tutte le tue ispezioni. Se si sta eseguendo un generatore di documentazione, ciò garantisce anche che tutte le opzioni siano documentate individualmente, piuttosto che raggruppate in una descrizione verbale.

Si noti che ho dichiarato il costruttore protected - questa è una preferenza personale, ma se ho intenzione di avere più di fabbrica-metodi statici, preferisco vedere quelli costantemente utilizzati in codice del consumo, piuttosto che a volte vedere Color::fromRGB(...) e altri tempi new Color(...).

Answer 4

Penso che sia meglio usare l'annotazione @method per classe/interfaccia, che dichiara i metodi di sovraccarico. Questa domanda è interessante anche per me.

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

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