Was ist der richtige Weg, um PHPDocs für Konstanten zu schreiben?

Ich habe diesen Code:

/**
 * Days to parse
 * @var int
 */
const DAYS_TO_PARSE = 10;
...

Ich denke nicht, dass die Verwendung @varfür eine Konstante korrekt ist und ich sehe kein @constantPHPDoc-Tag. Was ist der richtige Weg, um dies zu tun?

Um sie in phpDoc zu bekommen, verwenden Sie:

@const THING

Übliches Konstrukt:

@const[ant] label [description]

Die PHP-Figur schlägt vor, @varKonstanten zu verwenden.

7.22. @var

Mit dem @varTag können Sie den "Typ" der folgenden "Strukturelemente" dokumentieren:

• Konstanten, sowohl Klasse als auch globaler Bereich
• Eigenschaften
• Globale und lokale Variablen

Syntax

@var ["Type"] [element_name] [<description>]

@constist nicht die richtige Antwort.

• Es ist nicht Teil der alten phpDocumentor-Dokumente: http://manual.phpdoc.org/HTMLframesConverter/default/
• Es ist nicht Teil der aktuellen phpDocumentor-Dokumente: http://www.phpdoc.org/docs/latest/index.html
• Es ist nicht in der Liste der Tags auf Wikipedia aufgeführt: http://en.wikipedia.org/wiki/PHPDoc#Tags
• Es ist nicht im PHP-FIG-PSR-Entwurf aufgeführt: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#7-tags

Der einzige "offizielle" Ort, an dem es aufgeführt ist, ist phpdoc.de, aber die Spezifikation dort hat es immer nur auf 1.0beta geschafft, und die Site enthält auch Tags wie @brotherund @sister, die ich noch nie zuvor gesehen habe, also das allgemeine Vertrauen in diese Site ist etwas vermindert ;-) Der De-facto-Standard war schon immer phpDoc.org.

Kurz gesagt, selbst wenn ein inoffizieller Standard dies erwähnt, lohnt es sich nicht, es zu verwenden, wenn die Dokumentationsgeneratoren es nicht unterstützen.

@var ist richtig Fürs Erste, und wenn der PSR (letzter Link in der obigen Liste) nicht mehr im Entwurf ist und die Grundlage dafür ist, dass phpDocumentor, Doxygen, APIGen und andere PHPDoc verstehen, @typewäre dies der richtige Nachfolger@var.

Der Konstantentyp muss nicht mit Anmerkungen versehen werden, da der Typ immer wie folgt lautet:

• entweder ein Skalar oder ein Array
• zum Zeitpunkt der Deklaration bekannt
• unveränderlich

@constist auch nicht Teil des PHPDoc-Standards. PHP-FIG schlägt vor @var, dies wird jedoch nicht von PHPDoc unterstützt und fügt keine Informationen hinzu, die Sie nicht bereits aus der Deklaration selbst ableiten können.

Aus Gründen der Lesbarkeit empfehle ich daher, nur einen einfachen PHPDoc-Docblock zu verwenden, um Ihre Konstanten zu dokumentieren:

class Foo
{
    /**
     * This is a constant.
     */
    const BAR = 'bar';
}

Es beschreibt die Konstante beim Generieren von PHPDocs, hält die Kommentare jedoch sauber und lesbar.

Ich benutze Netbeans. Bei Verwendung dieses Formats wird phpDoc nach globalen Konstanten und Klassenkonstanten analysiert:

/** @const Global constant description */
define('MY_CONST', 10);

class MyClass
{
    /** @const Class constant description */
    const MY_CONST = 10;
}

Der folgende Vorschlag berücksichtigt die offizielle Dokumentationssyntax :

class Foo
{
    const
        /**
         * @var string Should contain a description
         */
        MY_CONST1 = "1",
        /**
         * @var string Should contain a description
         */
        MY_CONST2 = "2";

}