Que signifient les chaînes «# @ +» et «# @ -» dans les commentaires?

15

Je vois beaucoup de chaînes "# @ +" & "# @ -" dans les commentaires de certaines classes 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';
    /**#@-*/
    ...
}

Quel est le but de ces marqueurs?

— Alex Gusev
source

14

Ces caractères sont utilisés pour déclarer un modèle PHPDoc DocBlock :

Le but d'un modèle DocBlock est de réduire la saisie redondante. Par exemple, si un grand nombre de variables de classe sont privées, on utiliserait un modèle DocBlock pour les marquer comme privées. Les modèles DocBlock augmentent simplement tous les DocBlocks normaux trouvés dans le bloc de modèles.

Un modèle DocBlock se distingue d'un DocBlock normal par son en-tête.

/**#@+
 *
 */

Le texte qui le marque comme modèle DocBlock est "/ ** # @ +" - les 6 caractères doivent être présents. Les modèles DocBlock sont appliqués à tous les éléments documentables jusqu'au marqueur de modèle final:

/**#@-*/

Notez que les 8 caractères doivent apparaître sous la forme "/ ** # @ - * /" pour que phpDocumentor les reconnaisse comme modèle.

Plus d'informations peuvent être trouvées ici: http://codingexplained.com/coding/php/how-to-use-docblock-templates-in-phpdoc

Certaines explications sont également disponibles sur la documentation officielle de Magento: http://devdocs.magento.com/guides/v2.0/coding-standards/docblock-standard-general.html

— Raphael chez Digital Pianism
source

6

S'il y a déclaration de plusieurs éléments consécutifs de même type, le même contenu de DocBlock peut être pertinent pour chacun d'eux. Dans ce cas, les DocBlocks individuels pour ces éléments peuvent être remplacés par un modèle DocBlock.

Le modèle DocBlock se compose de deux commentaires DocBlock:

Le commentaire de départ est avant le premier élément du groupe, distingué à l'aide de # @ + et formaté comme suit:

/**#@+
 *
 */

Le commentaire de fin se situe après le dernier élément du groupe, distingué à l'aide de # @ - et formaté comme suit:/**#@-*/

Par exemple, déclaration de plusieurs constantes ou attributs 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();
    /**#@-*/

Référence ici

— Prashant Valanda
source