Wie verwende ich PHPDOC mit überlasteten Methoden?

Question

Nehmen wir an, ich habe eine PHP -Klasse angerufen Farbe, Es ist Konstruktor akzeptiert verschiedene 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');

Wie soll ich PHPDOC verwenden, um eine API -Dokumentation für Konstruktor und andere Methoden wie diese zu erstellen?

Wie verwende ich PHPDOC mit überlasteten Methoden?

class Color {

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

}

Answer 1

Da Sie Argumente für variable Länge zulassen, gibt es zwei Möglichkeiten, wie ich dies tun würde.

Ich würde einfach die zulässigen Argumente auflisten, sind Parameter.

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

Oder ich würde einfach eine Erklärung mit einigen Beispielen geben.

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

Eine andere Alternative, da nur eines der Beispiele mehr als ein Argument hat, wäre es, die Argumente in der Methodesignatur einfach zu definieren, die die letzten 2 optional machen. So was:

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

Answer 2

Nur meine Sichtweise, aber Sie sollten in erster Linie nicht mehrere Konstrukteure haben - Ihr Konstruktor wird voller If/sonst -Ladder sein, was wirklich keine gute Idee ist, besonders für etwas Leichtes wie eine Darstellung eines Farbe.

Ich ermutige Sie dringend, stattdessen so etwas auszuprobieren:

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

    ...
}

Jetzt im Verbrauchercode anstelle von etwas mysteriösen und mehrdeutigen Konstruktor -Aufrufen wie folgt:

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

Stattdessen können Sie lesbarere und semantischere Verbrauchercode wie folgt haben:

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

Dies ist wahrscheinlich sinnvoller für jemanden, der den Verbrauchercode liest. Er beseitigt die Logik, die erforderlich ist, um den mehrdeutigen Konstruktor zum Laufen zu bringen, und als Bonus (wenn Sie eine IDE wie PHPStorm verwenden) können Sie alle Ihre Inspektionen verabschieden. Wenn Sie einen Dokumentationsgenerator ausführen, stellt dies auch sicher, dass alle Optionen einzeln dokumentiert werden und nicht in einer verbalen Beschreibung zusammengefasst werden.

Beachten Sie, dass ich den Konstruktor erklärte protected - Dies ist eine persönliche Präferenz, aber wenn ich mehrere statische Fabrik-Methoden habe, bevorzuge ich diejenigen, die konsequent im Verbrauchercode verwendet werden, anstatt manchmal zu sehen Color::fromRGB(...) und andere Zeiten new Color(...).

Answer 3

Ich denke, das ist besser zu verwenden @method Annotation für Klassen/Schnittstelle, die Überladungsmethoden deklariert. Diese Frage ist auch für mich interessant.

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

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

Answer 4

Ich kenne keine elegante Möglichkeit, dies mit PHPDOC zu tun. Die Formatierung des Phpdoc -Kommentars/der API -Formatierung basiert auf einem der Javadoc Format. Javadoc verfügt über keine Funktion, um dies zu unterstützen, da in Java eine Methode eine variable Anzahl von Argumenten hat, die Sie für jede Variation erneut abdecken.

public double foo() {
}

public double foo(double my_param) {        
}

Meine Leistungspräferenz ist also so etwas wie

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

Dies spielt jedoch möglicherweise nicht gut mit den verschiedenen Auto-Documentation-Tools.

Die nach Hoyle -Art, dies zu erreichen, findet sich in der PHPDOC -Site.