Merge pull request #1207 from magento-performance/MAGETWO-69846

[Performance] @api annotation coverage and fixes

Author: kandy

app/code/Magento/Backend/App/AbstractAction.php

@@ -8,6 +8,7 @@
 /**
  * Generic backend controller
  *
+ * @api
  * @SuppressWarnings(PHPMD.NumberOfChildren)
  * @SuppressWarnings(PHPMD.CouplingBetweenObjects)
  */

app/code/Magento/Backend/App/Action.php

@@ -10,6 +10,7 @@
 namespace Magento\Backend\App;
 
 /**
+ * @api
  * @SuppressWarnings(PHPMD.NumberOfChildren)
  */
 abstract class Action extends \Magento\Backend\App\AbstractAction

app/code/Magento/Backend/App/Action/Context.php

@@ -8,7 +8,17 @@
 use Magento\Framework\Controller\ResultFactory;
 
 /**
- * Backend Controller context
+ * Constructor modification point for Magento\Backend\App\Action.
+ *
+ * All context classes were introduced to allow for backwards compatible constructor modifications
+ * of classes that were supposed to be extended by extension developers.
+ *
+ * Do not call methods of this class directly.
+ *
+ * As Magento moves from inheritance-based APIs all such classes will be deprecated together with
+ * the classes they were introduced for.
+ *
+ * @api
  * @SuppressWarnings(PHPMD.CouplingBetweenObjects)
  */
 class Context extends \Magento\Framework\App\Action\Context

app/code/Magento/Backend/Block/AbstractBlock.php

@@ -6,7 +6,12 @@
 namespace Magento\Backend\Block;
 
 /**
- * Backend abstract block
+ * Base for all admin blocks.
+ *
+ * Avoid using this class. Will be deprecated
+ *
+ * Marked as public API because it is actively used now.
+ * @api
  */
 class AbstractBlock extends \Magento\Framework\View\Element\AbstractBlock
 {

app/code/Magento/Backend/Block/Context.php

@@ -1,15 +1,22 @@
 <?php
 /**
- * Backend block context
- *
  * Copyright © Magento, Inc. All rights reserved.
  * See COPYING.txt for license details.
  */
 namespace Magento\Backend\Block;
 
 /**
- * Backend block context
+ * Constructor modification point for Magento\Backend\Block\AbstractBlock.
+ *
+ * All context classes were introduced to allow for backwards compatible constructor modifications
+ * of classes that were supposed to be extended by extension developers.
+ *
+ * Do not call methods of this class directly.
+ *
+ * As Magento moves from inheritance-based APIs all such classes will be deprecated together with
+ * the classes they were introduced for.
  *
+ * @api
  * @SuppressWarnings(PHPMD.CouplingBetweenObjects)
  */
 class Context extends \Magento\Framework\View\Element\Context

app/code/Magento/Backend/Block/Template.php

@@ -6,7 +6,20 @@
 namespace Magento\Backend\Block;
 
 /**
- * Backend abstract block
+ * Standard admin block. Adds admin-specific behavior and event.
+ * Should be used when you declare a block in admin layout handle.
+ *
+ * Avoid extending this class if possible.
+ *
+ * If you need custom presentation logic in your blocks, use this class as block, and declare
+ * custom view models in block arguments in layout handle file.
+ *
+ * Example:
+ * <block name="my.block" class="Magento\Backend\Block\Template" template="My_Module::template.phtml" >
+ *      <arguments>
+ *          <argument name="viewModel" xsi:type="object">My\Module\ViewModel\Custom</argument>
+ *      </arguments>
+ * </block>
  *
  * @api
  * @SuppressWarnings(PHPMD.NumberOfChildren)

app/code/Magento/Backend/Block/Template/Context.php

@@ -1,14 +1,22 @@
 <?php
 /**
- * Backend block template context
- *
  * Copyright © Magento, Inc. All rights reserved.
  * See COPYING.txt for license details.
  */
-
 namespace Magento\Backend\Block\Template;
 
 /**
+ * Constructor modification point for Magento\Backend\Block\Template.
+ *
+ * All context classes were introduced to allow for backwards compatible constructor modifications
+ * of classes that were supposed to be extended by extension developers.
+ *
+ * Do not call methods of this class directly.
+ *
+ * As Magento moves from inheritance-based APIs all such classes will be deprecated together with
+ * the classes they were introduced for.
+ *
+ * @api
  * @SuppressWarnings(PHPMD.CouplingBetweenObjects)
  */
 class Context extends \Magento\Framework\View\Element\Template\Context

app/code/Magento/Backend/Block/Widget.php

@@ -8,8 +8,7 @@
 /**
  * Base widget class
  *
- * @author     Magento Core Team <core@magentocommerce.com>
- *
+ * @api
  * @SuppressWarnings(PHPMD.NumberOfChildren)
  */
 class Widget extends \Magento\Backend\Block\Template

app/code/Magento/Backend/Block/Widget/Accordion.php

@@ -8,7 +8,7 @@
 /**
  * Magento_Backend accordion widget
  *
- * @author      Magento Core Team <core@magentocommerce.com>
+ * @api
  */
 class Accordion extends \Magento\Backend\Block\Widget
 {

app/code/Magento/Backend/Block/Widget/Context.php

@@ -3,10 +3,20 @@
  * Copyright © Magento, Inc. All rights reserved.
  * See COPYING.txt for license details.
  */
-
 namespace Magento\Backend\Block\Widget;
 
 /**
+ * Constructor modification point for Magento\Backend\Block\Widget.
+ *
+ * All context classes were introduced to allow for backwards compatible constructor modifications
+ * of classes that were supposed to be extended by extension developers.
+ *
+ * Do not call methods of this class directly.
+ *
+ * As Magento moves from inheritance-based APIs all such classes will be deprecated together with
+ * the classes they were introduced for.
+ *
+ * @api
  * @SuppressWarnings(PHPMD.CouplingBetweenObjects)
  */
 class Context extends \Magento\Backend\Block\Template\Context