Co oznaczają ciągi „# @ +” i „# @ -” w komentarzach?

15

Widzę wiele ciągów „# @ +” i „# @ -” w komentarzach niektórych klas 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';
    /**#@-*/
    ...
}

Jaki jest cel tych znaczników?

— Alex Gusev
źródło

14

Te znaki służą do deklarowania szablonu DocBlock w PHPDoc :

Celem szablonu DocBlock jest ograniczenie zbędnego pisania. Na przykład, jeśli duża liczba zmiennych klas jest prywatna, można użyć szablonu DocBlock, aby oznaczyć je jako prywatne. Szablony DocBlock po prostu rozszerzają wszelkie normalne DocBlocks znajdujące się w bloku szablonów.

Szablon DocBlock różni się od zwykłego DocBlock nagłówkiem.

/**#@+
 *
 */

Tekst oznaczający to jako szablon DocBlock to „/ ** # @ +” - wszystkie 6 znaków musi być obecne. Szablony DocBlock są stosowane do wszystkich dokumentowalnych elementów aż do znacznika końcowego:

/**#@-*/

Zauważ, że wszystkie 8 znaków musi pojawić się jako „/ ** # @ - * /”, aby phpDocumentor mógł je rozpoznać jako szablon.

Więcej informacji można znaleźć tutaj: http://codingexplained.com/coding/php/how-to-use-docblock-templates-in-phpdoc

Niektóre wyjaśnienia są także dostępne w oficjalnej dokumentacji Magento: http://devdocs.magento.com/guides/v2.0/coding-standards/docblock-standard-general.html

— Raphael at Digital Pianism
źródło

6

Jeśli istnieje deklaracja wielu kolejnych elementów tego samego typu, ta sama zawartość DocBlock może być odpowiednia dla wszystkich z nich. W takim przypadku poszczególne DocBlocks dla tych elementów mogą zostać zastąpione szablonem DocBlock.

Szablon DocBlock składa się z dwóch komentarzy DocBlock:

Komentarz początkowy jest przed pierwszym elementem grupy, wyróżnionym za pomocą # @ + i sformatowany w następujący sposób:

/**#@+
 *
 */

Końcowy komentarz jest po ostatnim elemencie grupy, wyróżnionym za pomocą # @ - i sformatowany w następujący sposób:/**#@-*/

Na przykład deklaracja wielu stałych klas lub atrybutów:

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

Odnośnik tutaj

— Prashant Valanda
źródło