¿Qué significan las cadenas "# @ +" y "# @ -" en los comentarios?

15

Veo muchas cadenas "# @ +" y "# @ -" en los comentarios de algunas clases de 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';
    /**#@-*/
    ...
}

¿Cuál es el propósito de estos marcadores?

— Alex Gusev
fuente

14

Esos caracteres se utilizan para declarar una plantilla PHPDoc DocBlock :

El propósito de una plantilla DocBlock es reducir la escritura redundante. Por ejemplo, si una gran cantidad de variables de clase son privadas, se usaría una plantilla DocBlock para marcarlas como privadas. Las plantillas DocBlock simplemente aumentan cualquier DocBlocks normal encontrado en el bloque de plantilla.

Una plantilla DocBlock se distingue de un DocBlock normal por su encabezado.

/**#@+
 *
 */

El texto que marca esto como plantilla de DocBlock es "/ ** # @ +": los 6 caracteres deben estar presentes. Las plantillas de DocBlock se aplican a todos los elementos documentables hasta el marcador de plantilla final:

/**#@-*/

Tenga en cuenta que los 8 caracteres deben aparecer como "/ ** # @ - * /" para que phpDocumentor los reconozca como una plantilla.

Puede encontrar más información aquí: http://codingexplained.com/coding/php/how-to-use-docblock-templates-in-phpdoc

Algunas explicaciones también están disponibles en la documentación oficial de Magento: http://devdocs.magento.com/guides/v2.0/coding-standards/docblock-standard-general.html

— Raphael en Digital Pianism
fuente

6

Si hay una declaración de múltiples elementos consecutivos del mismo tipo, el mismo contenido de DocBlock puede ser relevante para todos ellos. En este caso, DocBlocks individuales para esos elementos pueden ser reemplazados por una plantilla DocBlock.

La plantilla DocBlock consta de dos comentarios DocBlock:

El comentario inicial es antes del primer elemento del grupo, se distingue usando # @ + y se formatea de la siguiente manera:

/**#@+
 *
 */

El comentario final está después del último elemento del grupo, se distingue usando # @ y se formatea de la siguiente manera:/**#@-*/

Por ejemplo, declaración de constantes o atributos de clase múltiple:

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

Referencia aquí

— Prashant Valanda
fuente