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

79

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?

Elzo Valugi
quelle
Soweit definees betrifft: stackoverflow.com/questions/2192751/…
hakre
Ich habe gesehen, dass eine, definieren ist für eigenständige Konstanten, ich suche eine Klassenkonstante
Elzo Valugi
1
Mögliches Duplikat der Dokumentation zu phpDoc-Klassenkonstanten
hakre
@Elzo const FOO = 1;funktioniert auch außerhalb des Klassenkontexts.
Gordon
Dieser Typ verwendet @access private icosaedro.it/phplint/phpdoc.html , aber mir ist nicht bewusst, dass Sie die Sichtbarkeit für Konstanten einschränken können
Elzo Valugi

Antworten:

-19

Um sie in phpDoc zu bekommen, verwenden Sie:

@const THING

Übliches Konstrukt:

@const[ant] label [description]
Brian
quelle
Ist das nicht ein Unterschied zwischen Klassenkonstanten und globalen Konstanten, die durch define () initiiert wurden? Ich denke, @const dient dazu, letzteres zu notieren.
Januar
2
Es ist das erstere. Ich habe gerade eine Klassenkonstante dokumentiert und meine generierten PHPDOCs enthalten die Beschreibung korrekt. Und ab April 2017 haben die englischen Dokumente noch keine @const!
Keith
2
@constist ungültig und existiert nicht in PHPDocumentor. Verwenden Sie @var.
Wade
150

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>]

user2983026
quelle
1
Was ist also im Wesentlichen die Abkürzung für "Variable", die wir verwenden, um etwas zu dokumentieren, das "konstant" ist?
ankr
2
Ab 2017 wird mit using @constmeine Beschreibung korrekt ausgegeben, jedoch @varnichts für eine Klassenkonstante.
Keith
Das ist veraltet. In der aktuellen Version des PSR-5-Entwurfs wird dies nicht mehr ausdrücklich erwähnt. Ich behaupte, dass Konstanten keinen bestimmten Typhinweis
Yogarine
122

@constist nicht die richtige Antwort.

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.

GaryJ
quelle
1
Tatsächlich scheint es für IDEs überhaupt keine Rolle zu spielen. PHPStorm verwendet zum Beispiel immer den tatsächlichen Codewert, um den Typ herauszufinden (da ihm ein Wert zugewiesen sein muss).
Markieren Sie den
3

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.

Yogarine
quelle
2

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;
}
Sonny
quelle
1
Können Sie @constdie Klassenkonstanten in Netbeans nicht auslassen?
hakre
4
Ich habe gerade in Netbeans 8 getestet und konnte @constdie Deklarationen für globale und Klassenkonstanten weglassen .
Sonny
2

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";

}
Kwadz
quelle