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

[Performance] @api annotation coverage and fixes

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 <[email protected]>
- *
+ * @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 <[email protected]>
+ * @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

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

@@ -8,6 +8,8 @@
 /**
  * Backend form widget
  *
+ * @api
+ * @deprecated in favour of UI component implementation
  * @SuppressWarnings(PHPMD.NumberOfChildren)
  */
 class Form extends \Magento\Backend\Block\Widget

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

@@ -8,7 +8,8 @@
 /**
  * Backend form container block
  *
- * @author      Magento Core Team <[email protected]>
+ * @api
+ * @deprecated in favour of UI component implementation
  * @SuppressWarnings(PHPMD.NumberOfChildren)
  */
 class Container extends \Magento\Backend\Block\Widget\Container

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

@@ -3,14 +3,11 @@
  * Copyright © Magento, Inc. All rights reserved.
  * See COPYING.txt for license details.
  */
-
-/**
- * Backend form widget
- *
- */
 namespace Magento\Backend\Block\Widget\Form;
 
 /**
+ * @api
+ * @deprecated in favour of UI component implementation
  * @SuppressWarnings(PHPMD.NumberOfChildren)
  */
 class Generic extends \Magento\Backend\Block\Widget\Form

app/code/Magento/Backend/Block/Widget/Form/Renderer/Element.php

@@ -12,7 +12,8 @@
 /**
  * Form element default renderer
  *
- * @author      Magento Core Team <[email protected]>
+ * @api
+ * @deprecated in favour of UI component implementation
  */
 class Element extends \Magento\Backend\Block\Template implements RendererInterface
 {

app/code/Magento/Backend/Block/Widget/Form/Renderer/Fieldset/Element.php

@@ -12,7 +12,8 @@
 /**
  * Fieldset element renderer
  *
- * @author      Magento Core Team <[email protected]>
+ * @api
+ * @deprecated in favour of UI component implementation
  */
 class Element extends \Magento\Backend\Block\Template implements RendererInterface
 {

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

@@ -10,7 +10,7 @@
  * Backend grid widget block
  *
  * @api
- * @deprecated
+ * @deprecated in favour of UI component implementation
  * @method string getRowClickCallback() getRowClickCallback()
  * @method \Magento\Backend\Block\Widget\Grid setRowClickCallback() setRowClickCallback(string $value)
  * @SuppressWarnings(PHPMD.TooManyFields)

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

@@ -11,7 +11,7 @@
  * Grid column block
  *
  * @api
- * @deprecated
+ * @deprecated in favour of UI component implementation
  */
 class Column extends \Magento\Backend\Block\Widget
 {

app/code/Magento/Backend/Block/Widget/Grid/Column/Extended.php

@@ -5,6 +5,10 @@
  */
 namespace Magento\Backend\Block\Widget\Grid\Column;
 
+/**
+ * @api
+ * @deprecated in favour of UI component implementation
+ */
 class Extended extends \Magento\Backend\Block\Widget\Grid\Column
 {
     /**

app/code/Magento/Backend/Block/Widget/Grid/Column/Filter/AbstractFilter.php

@@ -4,11 +4,14 @@
  * See COPYING.txt for license details.
  */
 
+namespace Magento\Backend\Block\Widget\Grid\Column\Filter;
+
 /**
  * Grid column filter block
+ *
+ * @api
+ * @deprecated in favour of UI component implementation
  */
-namespace Magento\Backend\Block\Widget\Grid\Column\Filter;
-
 class AbstractFilter extends \Magento\Backend\Block\AbstractBlock implements
     \Magento\Backend\Block\Widget\Grid\Column\Filter\FilterInterface
 {

app/code/Magento/Backend/Block/Widget/Grid/Column/Filter/Select.php

@@ -8,7 +8,8 @@
 /**
  * Select grid column filter
  *
- * @author      Magento Core Team <[email protected]>
+ * @api
+ * @deprecated in favour of UI component implementation
  */
 class Select extends \Magento\Backend\Block\Widget\Grid\Column\Filter\AbstractFilter
 {

app/code/Magento/Backend/Block/Widget/Grid/Column/Multistore.php

@@ -9,7 +9,7 @@
  * Grid column block that is displayed only in multistore mode
  *
  * @api
- * @deprecated
+ * @deprecated in favour of UI component implementation
  */
 class Multistore extends \Magento\Backend\Block\Widget\Grid\Column
 {

app/code/Magento/Backend/Block/Widget/Grid/Column/Renderer/Action.php

@@ -9,7 +9,8 @@
 /**
  * Grid column widget for rendering action grid cells
  *
- * @author     Magento Core Team <[email protected]>
+ * @api
+ * @deprecated in favour of UI component implementation
  */
 class Action extends \Magento\Backend\Block\Widget\Grid\Column\Renderer\Text
 {

app/code/Magento/Backend/Block/Widget/Grid/Column/Renderer/Button.php

@@ -5,6 +5,10 @@
  */
 namespace Magento\Backend\Block\Widget\Grid\Column\Renderer;
 
+/**
+ * @api
+ * @SuppressWarnings(PHPMD.UnusedFormalParameter)
+ */
 class Button extends \Magento\Backend\Block\Widget\Grid\Column\Renderer\AbstractRenderer
 {
     /**

app/code/Magento/Backend/Block/Widget/Grid/Column/Renderer/Checkbox.php

@@ -8,7 +8,8 @@
 /**
  * Grid checkbox column renderer
  *
- * @author     Magento Core Team <[email protected]>
+ * @api
+ * @deprecated in favour of UI component implementation
  */
 class Checkbox extends \Magento\Backend\Block\Widget\Grid\Column\Renderer\AbstractRenderer
 {

app/code/Magento/Backend/Block/Widget/Grid/Column/Renderer/Concat.php

@@ -3,14 +3,14 @@
  * Copyright © Magento, Inc. All rights reserved.
  * See COPYING.txt for license details.
  */
+namespace Magento\Backend\Block\Widget\Grid\Column\Renderer;
 
 /**
  * Backend grid item renderer concat
  *
- * @author     Magento Core Team <[email protected]>
+ * @api
+ * @deprecated in favour of UI component implementation
  */
-namespace Magento\Backend\Block\Widget\Grid\Column\Renderer;
-
 class Concat extends \Magento\Backend\Block\Widget\Grid\Column\Renderer\AbstractRenderer
 {
     /**

app/code/Magento/Backend/Block/Widget/Grid/Column/Renderer/Country.php

@@ -3,12 +3,14 @@
  * Copyright © Magento, Inc. All rights reserved.
  * See COPYING.txt for license details.
  */
+namespace Magento\Backend\Block\Widget\Grid\Column\Renderer;
 
 /**
- * Country column renderer
+ * Country column type renderer
+ *
+ * @api
+ * @deprecated in favour of UI component implementation
  */
-namespace Magento\Backend\Block\Widget\Grid\Column\Renderer;
-
 class Country extends \Magento\Backend\Block\Widget\Grid\Column\Renderer\AbstractRenderer
 {
     /**

app/code/Magento/Backend/Block/Widget/Grid/Column/Renderer/Currency.php

@@ -9,7 +9,7 @@
 /**
  * Backend grid item renderer currency
  *
- * @author     Magento Core Team <[email protected]>
+ * @api
  */
 class Currency extends \Magento\Backend\Block\Widget\Grid\Column\Renderer\AbstractRenderer
 {

app/code/Magento/Backend/Block/Widget/Grid/Column/Renderer/Date.php

@@ -9,6 +9,8 @@
 
 /**
  * Backend grid item renderer date
+ * @api
+ * @deprecated in favour of UI component implementation
  */
 class Date extends \Magento\Backend\Block\Widget\Grid\Column\Renderer\AbstractRenderer
 {

app/code/Magento/Backend/Block/Widget/Grid/Column/Renderer/Datetime.php

@@ -3,12 +3,14 @@
  * Copyright © Magento, Inc. All rights reserved.
  * See COPYING.txt for license details.
  */
+namespace Magento\Backend\Block\Widget\Grid\Column\Renderer;
 
 /**
  * Backend grid item renderer datetime
+ *
+ * @api
+ * @deprecated in favour of UI component implementation
  */
-namespace Magento\Backend\Block\Widget\Grid\Column\Renderer;
-
 class Datetime extends \Magento\Backend\Block\Widget\Grid\Column\Renderer\AbstractRenderer
 {
     /**

app/code/Magento/Backend/Block/Widget/Grid/Column/Renderer/DraggableHandle.php

@@ -5,6 +5,10 @@
  */
 namespace Magento\Backend\Block\Widget\Grid\Column\Renderer;
 
+/**
+ * @api
+ * @deprecated in favour of UI component implementation
+ */
 class DraggableHandle extends \Magento\Backend\Block\Widget\Grid\Column\Renderer\AbstractRenderer
 {
     /**