Что означают строки «# @ +» и «# @ -» в комментариях?

15

Я вижу много строк "# @ +" и "# @ -" в комментариях некоторых классов 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';
    /**#@-*/
    ...
}

Какова цель этих маркеров?

— Алекс Гусев
источник

14

Эти символы используются для объявления шаблона PHPDoc DocBlock :

Целью шаблона DocBlock является сокращение избыточной типизации. Например, если большое количество переменных класса являются закрытыми, можно использовать шаблон DocBlock, чтобы пометить их как частные. Шаблоны DocBlock просто дополняют любые обычные DocBlocks, найденные в блоке шаблонов.

Шаблон DocBlock отличается от обычного DocBlock своим заголовком.

/**#@+
 *
 */

Текст, который помечает это как шаблон DocBlock - «/ ** # @ +» - должны присутствовать все 6 символов. Шаблоны DocBlock применяются ко всем документируемым элементам до конечного маркера шаблона:

/**#@-*/

Обратите внимание, что все 8 символов должны отображаться как "/ ** # @ - * /", чтобы phpDocumentor распознал их как шаблон.

Дополнительную информацию можно найти здесь: http://codingexplained.com/coding/php/how-to-use-docblock-templates-in-phpdoc

Некоторые объяснения также доступны в официальной документации Magento: http://devdocs.magento.com/guides/v2.0/coding-standards/docblock-standard-general.html

— Рафаэль в цифровом пианизме
источник

6

Если существует объявление нескольких последовательных элементов одного и того же типа, одинаковое содержимое DocBlock может относиться ко всем из них. В этом случае отдельные DocBlocks для этих элементов могут быть заменены шаблоном DocBlock.

Шаблон DocBlock состоит из двух комментариев DocBlock:

Начальный комментарий перед первым элементом группы, различается с помощью # @ + и форматируется следующим образом:

/**#@+
 *
 */

Конечный комментарий следует за последним элементом группы, различается с помощью # @ и форматируется следующим образом:/**#@-*/

Например, объявление нескольких констант или атрибутов класса:

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

Ссылка здесь

— Прашант Валанда
источник