O que significam as strings "# @ +" e "# @ -" nos comentários?

15

Eu vejo muitas strings "# @ +" e "# @ -" nos comentários de algumas classes do 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 é o objetivo desses marcadores?

— Alex Gusev
fonte

14

Esses caracteres são usados para declarar um modelo PHPDoc DocBlock :

O objetivo de um modelo DocBlock é reduzir a digitação redundante. Por exemplo, se um grande número de variáveis de classe for particular, seria usado um modelo DocBlock para marcá-las como privadas. Os modelos DocBlock simplesmente aumentam qualquer DocBlocks normal encontrado no bloco de modelos.

Um modelo DocBlock se diferencia de um DocBlock normal por seu cabeçalho.

/**#@+
 *
 */

O texto que marca isso como um modelo do DocBlock é "/ ** # @ +" - todos os 6 caracteres devem estar presentes. Os modelos DocBlock são aplicados a todos os elementos documentáveis até o marcador final do modelo:

/**#@-*/

Observe que todos os 8 caracteres devem aparecer como "/ ** # @ - * /" para que o phpDocumentor os reconheça como um modelo.

Mais informações podem ser encontradas aqui: http://codingexplained.com/coding/php/how-to-use-docblock-templates-in-phpdoc

Algumas explicações também estão disponíveis na documentação oficial do Magento: http://devdocs.magento.com/guides/v2.0/coding-standards/docblock-standard-general.html

— Raphael na Digital Pianism
fonte

6

Se houver declaração de vários elementos consecutivos do mesmo tipo, o mesmo conteúdo do DocBlock poderá ser relevante para todos eles. Nesse caso, DocBlocks individuais para esses elementos podem ser substituídos por um modelo DocBlock.

O modelo DocBlock consiste em dois comentários do DocBlock:

O comentário inicial é anterior ao primeiro elemento do grupo, distinguido usando # @ + e formatado da seguinte maneira:

/**#@+
 *
 */

O comentário final é após o último elemento do grupo, distinguido usando # @ - e formatado da seguinte forma:/**#@-*/

Por exemplo, declaração de várias constantes ou atributos de classe:

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

Referência aqui

— Prashant Valanda
fonte