diff --git a/core/lib/Drupal/Core/Config/Entity/ConfigDependencyManager.php b/core/lib/Drupal/Core/Config/Entity/ConfigDependencyManager.php
index f52aad0..d2f4208 100644
--- a/core/lib/Drupal/Core/Config/Entity/ConfigDependencyManager.php
+++ b/core/lib/Drupal/Core/Config/Entity/ConfigDependencyManager.php
@@ -14,10 +14,21 @@
  * Provides a class to discover configuration entity dependencies.
  *
  * Configuration entities can depend on modules, themes and other configuration
- * entities. The dependency system is used during configuration installation to
- * ensure that configuration entities are imported in the correct order. For
- * example, node types are created before their field storages and the field
- * storages are created before their fields.
+ * entities. The dependency system is used during configuration installation
+ * and removal to ensure that configuration entities are handled in the correct
+ * order. For example, node types are created before their field storages and
+ * the field storages are created before their fields.
+ *
+ * Dependencies in configuration do not supersede dependencies of containing
+ * modules/themes/profiles. For example if a view is shipped with an install
+ * profile and the view requires a 3rd party field module, the configuration
+ * will still be installed even if the profile does not require the module
+ * providing the field type. It is the responsibility of the containing project
+ * to depend on required modules. To include configuration that depends on
+ * optional 3rd party modules, add submodules that depend on that module in your
+ * project. The configuration dependency system is only used to manage ordering
+ * in the install/import processes and remove configuration in the module
+ * uninstall process.
  *
  * Dependencies are stored to the configuration entity's configuration object so
  * that they can be checked without the module that provides the configuration
@@ -37,14 +48,39 @@
  * plugin providers for configuration entities that implement
  * \Drupal\Core\Entity\EntityWithPluginBagsInterface.
  *
+ * \Drupal\Core\Plugin\PluginDependencyTrait is also provided for convenience
+ * to calculate plugin based dependencies. Also used by configuration entities,
+ * this lets system menu blocks to depend on the displayed menu entity. This is
+ * crucial to ensure a configuration import will import the menu first before
+ * the block is saved on the system.
+ *
  * The configuration manager service provides methods to find dependencies for
  * a specified module, theme or configuration entity.
  *
+ * When dependent items are removed (such a module providing a field type is
+ * uninstalled), configuration that was dependent will also be removed. This
+ * may lead to unintended side effects (eg. node types and displays being
+ * removed on uninstall of a field), so a more fine grained mechanism is
+ * provided to respond to dependency removal.
+ * \Drupal\Core\Config\Entity\ConfigEntityInterface::onDependencyRemoval() is
+ * invoked to allow configuration entities to respond if any of their
+ * dependencies is going to be removed (ie. if an entity is going to be deleted
+ * or a module uninstalled). This method allows configuration entities to remove
+ * dependencies instead of being deleted themselves. When a module is being
+ * uninstalled, configuration entities can use this method to avoid being
+ * unnecessarily deleted. Implementations should save the entity if dependencies
+ * have been successfully removed.
+ *
+ * For example, entity displays remove references to widgets and formatters if
+ * the plugin that supplies them depends on a module that is being uninstalled.
+ *
  * @see \Drupal\Core\Config\Entity\ConfigEntityInterface::calculateDependencies()
  * @see \Drupal\Core\Config\Entity\ConfigEntityInterface::getConfigDependencyName()
+ * @see \Drupal\Core\Config\Entity\ConfigEntityInterface::onDependencyRemoval()
  * @see \Drupal\Core\Config\Entity\ConfigEntityBase::addDependency()
  * @see \Drupal\Core\Config\ConfigInstaller::installDefaultConfig()
  * @see \Drupal\Core\Config\Entity\ConfigEntityDependency
+ * @see \Drupal\Core\Plugin\PluginDependencyTrait
  */
 class ConfigDependencyManager {
 
diff --git a/core/lib/Drupal/Core/Config/Entity/ConfigEntityInterface.php b/core/lib/Drupal/Core/Config/Entity/ConfigEntityInterface.php
index dd76d23..3b18c0a 100644
--- a/core/lib/Drupal/Core/Config/Entity/ConfigEntityInterface.php
+++ b/core/lib/Drupal/Core/Config/Entity/ConfigEntityInterface.php
@@ -156,6 +156,8 @@ public function calculateDependencies();
    *
    * @return string
    *   The configuration dependency name.
+   *
+   * @see \Drupal\Core\Config\Entity\ConfigDependencyManager
    */
   public function getConfigDependencyName();
 
@@ -178,6 +180,7 @@ public function getConfigDependencyName();
    *   An array of dependencies that will be deleted keyed by dependency type.
    *   Dependency types are, for example, entity, module and theme.
    *
+   * @see \Drupal\Core\Config\Entity\ConfigDependencyManager
    * @see \Drupal\Core\Config\ConfigManager::uninstall()
    * @see \Drupal\Core\Entity\EntityDisplayBase::onDependencyRemoval()
    */
@@ -189,6 +192,8 @@ public function onDependencyRemoval(array $dependencies);
    * @return array
    *   An array of dependencies. If $type not set all dependencies will be
    *   returned keyed by $type.
+   *
+   * @see \Drupal\Core\Config\Entity\ConfigDependencyManager
    */
   public function getDependencies();