MAGETWO-70716: Provide entity manager description

Author: Valeriy Nayda

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

@@ -12,17 +12,15 @@
 use Magento\Framework\EntityManager\Operation\UpdateInterface;
 
 /**
- * Class EntityManager
- *
- * It's not recommended to use EntityManager and its infrastructure for your entity persistence.
+ * 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.
  *
  * For filtering operations, it's recommended to use successor of
- * Magento\Framework\Model\ResourceModel\Db\Collection\AbstractCollection
+ * Magento\Framework\Model\ResourceModel\Db\Collection\AbstractCollection class.
  */
 class EntityManager
 {

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

@@ -1,7 +1,8 @@
 # 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 
@@ -11,4 +12,4 @@ Currently, it's recommended to use Resource Model infrastructure and make a succ
 Magento\Framework\Model\ResourceModel\Db\AbstractDb class.
 
 For filtering operations, it's recommended to use successor of 
-Magento\Framework\Model\ResourceModel\Db\Collection\AbstractCollection
+Magento\Framework\Model\ResourceModel\Db\Collection\AbstractCollection class.