Issue #2112045 by Wim Leers, Berdir: Fix up documentation for cache tags

core/lib/Drupal/Component/Plugin/Discovery/CachedDiscoveryInterface.php

@@ -14,6 +14,10 @@ interface CachedDiscoveryInterface extends DiscoveryInterface {
 
   /**
    * Clears static and persistent plugin definition caches.
+   *
+   * Don't resort to calling \Drupal::cache()->delete() and friends to make
+   * Drupal detect new or updated plugin definitions. Always use this method on
+   * the appropriate plugin type's plugin manager!
    */
   public function clearCachedDefinitions();
 

core/lib/Drupal/Core/Plugin/DefaultPluginManager.php

@@ -121,8 +121,13 @@ public function __construct($subdir, \Traversable $namespaces, $plugin_definitio
    *   Cache key prefix to use, the language code will be appended
    *   automatically.
    * @param array $cache_tags
-   *   (optional) When providing a list of cache tags, the cached definitions
-   *   are tagged and are used to clear the cache.
+   *   (optional) When providing a list of cache tags, the cached plugin
+   *   definitions are tagged with the provided cache tags. These cache tags can
+   *   then be used to clear the corresponding cached plugin definitions. Note
+   *   that this should be used with care! For clearing all cached plugin
+   *   definitions of a plugin manager, call that plugin manager's
+   *   clearCachedDefinitions() method. Only use cache tags when cached plugin
+   *   definitions should be cleared along with other, related cache entries.
    */
   public function setCacheBackend(CacheBackendInterface $cache_backend, LanguageManager $language_manager, $cache_key_prefix, array $cache_tags = array()) {
     $this->languageManager = $language_manager;