Cosa significano le stringhe "# @ +" e "# @ -" nei commenti?

15

Vedo molte stringhe "# @ +" e "# @ -" nei commenti di alcune classi di Magento 2. \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';
    /**#@-*/
    ...
}

Qual è lo scopo di questi marcatori?

— Alex Gusev
fonte

14

Quei personaggi sono usati per dichiarare un template DocBlock PHPDoc :

Lo scopo di un modello DocBlock è ridurre la digitazione ridondante. Ad esempio, se un gran numero di variabili di classe sono private, si userebbe un modello DocBlock per contrassegnarle come private. I modelli DocBlock aumentano semplicemente qualsiasi normale DocBlock trovato nel blocco modello.

Un modello DocBlock si distingue da un normale DocBlock per la sua intestazione.

/**#@+
 *
 */

Il testo che lo contrassegna come modello DocBlock è "/ ** # @ +" - devono essere presenti tutti e 6 i caratteri. I modelli DocBlock vengono applicati a tutti gli elementi documentabili fino al marcatore del modello finale:

/**#@-*/

Si noti che tutti e 8 i caratteri devono apparire come "/ ** # @ - * /" affinché phpDocumentor li riconosca come modello.

Maggiori informazioni sono disponibili qui: http://codingexplained.com/coding/php/how-to-use-docblock-templates-in-phpdoc

Alcune spiegazioni sono disponibili anche sulla documentazione ufficiale di Magento: http://devdocs.magento.com/guides/v2.0/coding-standards/docblock-standard-general.html

— Raffaello al Pianismo digitale
fonte

6

Se esiste una dichiarazione di più elementi consecutivi dello stesso tipo, lo stesso contenuto di DocBlock può essere rilevante per tutti. In questo caso, singoli DocBlock per tali elementi possono essere sostituiti da un modello DocBlock.

Il modello DocBlock è composto da due commenti DocBlock:

Il commento iniziale è prima del primo elemento del gruppo, distinto usando # @ + e formattato come segue:

/**#@+
 *
 */

Il commento finale termina dopo l'ultimo elemento del gruppo, distinto usando # @ - e formattato come segue:/**#@-*/

Ad esempio, dichiarazione di costanti o attributi di più classi:

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();
    /**#@-*/

Riferimento qui

— Prashant Valanda
fonte