Merge remote-tracking branch 'dragons/MAGETWO-70716' into pr-2.2

Author: andimov

lib/internal/Magento/Framework/EntityManager/EntityManager.php

@@ -12,7 +12,18 @@
 use Magento\Framework\EntityManager\Operation\UpdateInterface;
 
 /**
- * Class EntityManager
+ * It's not recommended to use EntityManager and its infrastructure for your entities persistence.
+ * In the nearest future new Persistence Entity Manager would be released which will cover all the requirements for
+ * persistence layer along with Query API as performance efficient APIs for Read scenarios.
+ *
+ * Currently, it's recommended to use Resource Model infrastructure and make a successor of
+ * Magento\Framework\Model\ResourceModel\Db\AbstractDb class or successor of
+ * Magento\Eav\Model\Entity\AbstractEntity if EAV attributes support needed.
+ *
+ * For filtering operations, it's recommended to use successor of
+ * Magento\Framework\Model\ResourceModel\Db\Collection\AbstractCollection class.
+ *
+ * @SuppressWarnings(PHPMD.CouplingBetweenObjects)
  */
 class EntityManager
 {

lib/internal/Magento/Framework/EntityManager/README.md

@@ -1,4 +1,16 @@
 # EntityManager
 
-**EntityManager** library contains functionality for management entity instances.
-It includes read and write operations as for entity as for their attributes and extensions.
+**EntityManager** library contains functionality for entity persistence layer.
+EntityManager supports persistence of basic entity attributes as well as extension and custom attributes 
+added by 3rd party developers for the purpose of extending default entity behavior.
+
+It's not recommended to use EntityManager and its infrastructure for your entity persistence.
+In the nearest future new Persistence Entity Manager would be released which will cover all the requirements for 
+persistence layer along with Query API as performance efficient APIs for Read scenarios.
+
+Currently, it's recommended to use Resource Model infrastructure and make a successor of 
+Magento\Framework\Model\ResourceModel\Db\AbstractDb class or successor of 
+Magento\Eav\Model\Entity\AbstractEntity if EAV attributes support needed.
+
+For filtering operations, it's recommended to use successor of 
+Magento\Framework\Model\ResourceModel\Db\Collection\AbstractCollection class.