Was bedeuten die Zeichenfolgen "# @ +" und "# @ -" in den Kommentaren?

15

In den Kommentaren einiger Magento 2-Klassen sehe ich viele "# @ +" und "# @ -" Zeichenfolgen. \Magento\Customer\Api\Data\AttributeMetadataInterface

interface AttributeMetadataInterface extends \Magento\Framework\Api\MetadataObjectInterface
{
    /**#@+
     * Constants used as keys of data array
     */
    const ATTRIBUTE_CODE = 'attribute_code';
    ...
    const IS_SEARCHABLE_IN_GRID = 'is_searchable_in_grid';
    /**#@-*/
    ...
}

Was ist der Zweck dieser Marker?

Alex Gusev
quelle

Antworten:

14

Diese Zeichen werden verwendet , um eine PHPDoc DocBlock-Vorlage zu deklarieren :

Der Zweck einer DocBlock-Vorlage besteht darin, die redundante Eingabe zu reduzieren. Wenn zum Beispiel eine große Anzahl von Klassenvariablen privat ist, würde man eine DocBlock-Vorlage verwenden, um sie als privat zu kennzeichnen. DocBlock-Vorlagen erweitern einfach alle normalen DocBlocks im Vorlagenblock.

Eine DocBlock-Vorlage unterscheidet sich von einem normalen DocBlock durch ihre Kopfzeile.

/**#@+
 *
 */

Der Text, der dies als DocBlock-Vorlage kennzeichnet, lautet "/ ** # @ +" - alle 6 Zeichen müssen vorhanden sein. DocBlock-Vorlagen werden auf alle dokumentierbaren Elemente angewendet, bis die letzte Vorlagenmarkierung erreicht ist:

/**#@-*/

Beachten Sie, dass alle 8 Zeichen als "/ ** # @ - * /" angezeigt werden müssen, damit phpDocumentor sie als Vorlage erkennt.

Weitere Informationen finden Sie hier: http://codingexplained.com/coding/php/how-to-use-docblock-templates-in-phpdoc

Einige Erklärungen finden Sie auch in der offiziellen Magento-Dokumentation: http://devdocs.magento.com/guides/v2.0/coding-standards/docblock-standard-general.html

Raphael beim digitalen Pianismus
quelle
6

Wenn mehrere aufeinanderfolgende Elemente desselben Typs deklariert werden, kann derselbe Inhalt von DocBlock für alle von Bedeutung sein. In diesem Fall können einzelne DocBlocks für diese Elemente durch eine DocBlock-Vorlage ersetzt werden.

Die DocBlock-Vorlage besteht aus zwei DocBlock-Kommentaren:

Der Startkommentar befindet sich vor dem ersten Element der Gruppe, wird mit # @ + unterschieden und wie folgt formatiert:

/**#@+
 *
 */

Der abschließende Kommentar steht nach dem letzten Element der Gruppe und wird durch # @ - unterschieden und wie folgt formatiert:/**#@-*/

Zum Beispiel Deklaration mehrerer Klassenkonstanten oder Attribute:

class Mage_Core_Model_Layout extends Varien_Simplexml_Config
{
    /**#@+
     * Supported layout directives
     * @var string
     */
    const TYPE_BLOCK = 'block';
    const TYPE_CONTAINER = 'container';
    /**#@-*/

    /**#@+
     * Scheduled structure elements operations
     *
     * @var array
     */
    protected $scheduledMoves   = array();
    protected $scheduledRemoves = array();
    /**#@-*/

Referenz hier

Prashant Valanda
quelle