Wie schreibt man PHPDocs für Konstanten richtig?

Lesezeit: 4 Minuten

Benutzer-Avatar
Elzo Valugi

Ich habe diesen Code:

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

Ich denke nicht, dass mit @var ist korrekt für eine Konstante und ich sehe keine @constant PHPDoc-Tag. Was ist der richtige Weg, dies zu tun?

  • So weit wie define ist besorgt: stackoverflow.com/questions/2192751/…

    – hakre

    15. Juli 2011 um 11:08 Uhr

  • Ich habe das gesehen, define ist für eigenständige Konstanten, ich suche nach einer Klassenkonstante

    – Elzo Valugi

    15. Juli 2011 um 11:10 Uhr


  • mögliches Duplikat der Dokumentation der phpDoc-Klassenkonstanten

    – hakre

    15. Juli 2011 um 11:10 Uhr

  • @Elzo const FOO = 1; funktioniert auch außerhalb des Klassenkontextes.

    – Gordon

    15. Juli 2011 um 11:13 Uhr

  • Dieser Typ verwendet @access private icosaedro.it/phplint/phpdoc.htmlaber mir ist nicht bewusst, dass Sie die Sichtbarkeit für Konstanten einschränken können

    – Elzo Valugi

    15. Juli 2011 um 11:16 Uhr

Benutzer-Avatar
Benutzer2983026

Die PHP-FIG schlägt die Verwendung vor @var für Konstanten.

7.22. @var

Sie können die verwenden @var Tag, um den “Typ” der folgenden “Strukturelemente” zu dokumentieren:

  • Konstanten, sowohl Klassen- als auch globaler Geltungsbereich
  • Eigenschaften
  • Variablen, sowohl global als auch lokal

Syntax

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

  • Was ist also im Wesentlichen die Abkürzung für „Variable“, die wir verwenden, um etwas zu dokumentieren, das „konstant“ ist?

    – ankr

    2. Januar 2017 um 12:34 Uhr

  • ab 2017 verwenden @const wird meine Beschreibung aber korrekt ausgeben @var gibt nichts für eine Klassenkonstante aus.

    – Keith

    20. April 2017 um 19:28 Uhr

  • Das ist veraltet. Die aktuelle Version des PSR-5-Entwurfs erwähnt dies nicht mehr ausdrücklich. Ich behaupte, dass Konstanten keinen bestimmten Typhinweis benötigen, da ihr Typ unveränderlich ist und immer abgeleitet werden kann: stackoverflow.com/a/50945077/752110

    – Yogarin

    27. Juli 2020 um 10:29 Uhr

  • @Yogarine-Konstanten benötigen möglicherweise keinen Typhinweis, aber es kann wünschenswert sein, zu dokumentieren, wofür die Konstante verwendet wird

    – Brad Kent

    11. Januar 2021 um 3:46 Uhr

  • @BradKent Natürlich. In diesem Fall reicht es aus, einfach einen Docblock ohne Anmerkungen hinzuzufügen.

    – Yogarin

    24. Februar 2021 um 11:41 Uhr


Benutzer-Avatar
GaryJ

@const ist 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 bis 1.0beta geschafft, und die Site enthält auch Tags wie @brother und @sisterdie ich noch nie zuvor gesehen habe, daher ist das allgemeine Vertrauen in diese Site etwas geschmälert 😉 Der De-facto-Standard war schon immer phpDoc.org.

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

@var ist richtig für den Moment und sobald der PSR (letzter Link in der obigen Liste) aus dem Entwurf ist und die Grundlage ist, für die phpDocumentor, Doxygen, APIGen und andere PHPDoc verstehen, dann @type wäre richtig, welches der Nachfolger ist @var.

  • Letztlich, @type wurde zugunsten von fallen gelassen @var.

    – aussen

    20. August 2015 um 21:29 Uhr

  • Tatsächlich scheint es für IDEs überhaupt keine Rolle zu spielen, PHPStorm zum Beispiel nimmt immer den tatsächlichen Codewert, um den Typ herauszufinden (da ihm ein Wert zugewiesen werden muss).

    – Kennzeichen

    22. August 2016 um 9:34 Uhr

Benutzer-Avatar
Yogarin

Es ist nicht erforderlich, den Typ von Konstanten zu kommentieren, da der Typ immer ist:

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

@const ist 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 verwende Netbeans. Es wird phpDoc nach globalen und Klassenkonstanten durchsuchen, wenn dieses Format verwendet wird:

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

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

Folgende Vorschlag respektiert die offizielle Dokumentationssyntax:

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

}

Benutzer-Avatar
Brian

Um sie in phpDoc zu bekommen, verwenden Sie:

@const THING

Übliches Konstrukt:

@const[ant] label What is the correct way to write PHPDocs for constants?

1352600cookie-checkWie schreibt man PHPDocs für Konstanten richtig?

This website is using cookies to improve the user-friendliness. You agree by using the website further.

Privacy policy