#27536: Improved interfaces comments and introduced MediaContentCms sequence

Author: sivaschenko

app/code/Magento/Cms/etc/module.xml

@@ -11,6 +11,7 @@
             <module name="Magento_Store"/>
             <module name="Magento_Theme"/>
             <module name="Magento_Variable"/>
+            <module name="Magento_MediaContentCms"/>
         </sequence>
     </module>
 </config>

app/code/Magento/MediaContentApi/Api/AssignAssetsInterface.php

@@ -11,13 +11,13 @@
 use Magento\MediaContentApi\Api\Data\ContentIdentityInterface;
 
 /**
- * Saving data represents relation between the media asset and media content
+ * Assign a media asset to the piece of content. Should be executed when media assets is added to the content
  * @api
  */
 interface AssignAssetsInterface
 {
     /**
-     * Save relation between media asset and media content.
+     * Assign a media asset to the piece of content. Should be executed when media assets is added to the content
      *
      * @param ContentIdentityInterface $contentIdentity
      * @param int[] $assetIds

app/code/Magento/MediaContentApi/Api/ExtractAssetsFromContentInterface.php

@@ -10,13 +10,13 @@
 use Magento\MediaGalleryApi\Api\Data\AssetInterface;
 
 /**
- * Used for extracting media asset list from a media content by the search pattern.
+ * Parse the content string for references to media assets and return the list of identified media assets
  * @api
  */
 interface ExtractAssetsFromContentInterface
 {
     /**
-     * Search for the media asset in content and extract it providing a list of media assets.
+     * Parse the content string for references to media assets and return the list of identified media assets
      *
      * @param string $content
      * @return AssetInterface[]

app/code/Magento/MediaContentApi/Api/GetAssetIdsUsedInContentInterface.php

@@ -11,13 +11,13 @@
 use Magento\MediaContentApi\Api\Data\ContentIdentityInterface;
 
 /**
- * Get media asset ids used in the content
+ * Get media asset ids that are used in the piece of content identified by the specified content identity
  * @api
  */
 interface GetAssetIdsUsedInContentInterface
 {
     /**
-     * Get media asset ids used in the content
+     * Get media asset ids that are used in the piece of content identified by the specified content identity
      *
      * @param ContentIdentityInterface $contentIdentity
      * @return int[]

app/code/Magento/MediaContentApi/Api/GetContentWithAssetsInterface.php

@@ -11,13 +11,13 @@
 use Magento\MediaContentApi\Api\Data\ContentIdentityInterface;
 
 /**
- * Get media content list which is used with the specified media asset
+ * Get list of content identifiers for pieces of content that include the specified media asset
  * @api
  */
 interface GetContentWithAssetsInterface
 {
     /**
-     * Get media asset to content relations by media asset id.
+     * Get list of content identifiers for pieces of content that include the specified media asset
      *
      * @param int[] $assetIds
      * @return ContentIdentityInterface[]

app/code/Magento/MediaContentApi/Api/UnassignAssetsInterface.php

@@ -11,13 +11,13 @@
 use Magento\MediaContentApi\Api\Data\ContentIdentityInterface;
 
 /**
- * Unassign relation between the media asset and media content where the media asset is used
+ * Remove the relation between media asset and the piece of content. I.e media asset no longer part of the content
  * @api
  */
 interface UnassignAssetsInterface
 {
     /**
-     * Remove relation between the media asset and media content.
+     * Remove relation between the media asset and the content. I.e media asset no longer part of the content
      *
      * @param int[] $assetIds
      * @param ContentIdentityInterface $contentIdentity

app/code/Magento/MediaContentApi/Api/UpdateRelationsInterface.php

@@ -10,12 +10,12 @@
 use Magento\MediaContentApi\Api\Data\ContentIdentityInterface;
 
 /**
- * Process relation managing between media asset and content: assign or unassign relation if exists.
+ * Update the media assets to content relations. Assign new media assets and unassign media assets no longer used
  */
 interface UpdateRelationsInterface
 {
     /**
-     * Create new relation between media asset and content or updated existing
+     * Update the media assets to content relations. Assign new media assets and unassign media assets no longer used
      *
      * @param ContentIdentityInterface $contentIdentity
      * @param string $content

app/code/Magento/MediaContentCms/etc/module.xml

@@ -6,5 +6,7 @@
  */
 -->
 <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
-    <module name="Magento_MediaContentCms" />
+    <module name="Magento_MediaContentCms">
+        <module name="Magento_MediaContent"/>
+    </module>
 </config>