Що означають рядки "# @ +" & "# @ -" у коментарях?

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

Довідка тут

— Прашант Валанда
джерело