diff --git a/core/lib/Drupal/Core/Plugin/Discovery/YamlDiscovery.php b/core/lib/Drupal/Core/Plugin/Discovery/YamlDiscovery.php
index f5d7c74..b4a6f0e 100644
--- a/core/lib/Drupal/Core/Plugin/Discovery/YamlDiscovery.php
+++ b/core/lib/Drupal/Core/Plugin/Discovery/YamlDiscovery.php
@@ -15,11 +15,12 @@
 /**
  * Allows YAML files to define plugin definitions.
  *
- * For translatable values of plugin defintions, like title, you can add
- * translatable properties using addTranslatableProperty(). This is used in
- * order to use a translation wrapper to 100% indicate that something is safe,
- * as it was written in the YAML file and did not come from a dynamic plugin
- * definition.
+ * If the value of a key (like title) in the definition is translatable then
+ * the addTranslatableProperty() can be used to mark it as such and also to add
+ * translation context. Then \Drupal\Core\StringTranslation\TranslationWrapper
+ * will be used to translate the string and also to mark it safe. Only strings
+ * written in the YAML files should be marked as safe, strings coming from
+ * dynamic plugin definitions potentially containing user input should not.
  */
 class YamlDiscovery implements DiscoveryInterface {