diff --git a/core/lib/Drupal/Component/Utility/FormattableString.php b/core/lib/Drupal/Component/Utility/FormattableString.php
index 6367b86..1dba94a 100644
--- a/core/lib/Drupal/Component/Utility/FormattableString.php
+++ b/core/lib/Drupal/Component/Utility/FormattableString.php
@@ -10,12 +10,9 @@
 /**
  * Formats a string for HTML display by replacing variable placeholders.
  *
- * When cast to a string it replaces variable placeholders in the string with
- * the arguments passed in during construction and escapes the values so they
- * can be safely displayed as HTML. It should be used on any unknown text that
- * is intended to be printed to an HTML page (especially text that may have come
- * from untrusted users, since in that case it prevents cross-site scripting and
- * other security problems).
+ * When cast to a string, this object replaces variable placeholders in the
+ * string with the arguments passed in during construction and escapes the
+ * values so they can be safely displayed as HTML.
  *
  * In most cases, you should use TranslatableString or PluralTranslatableString
  * rather than this object, since they will translate the text (on
@@ -28,18 +25,23 @@
  * not as an HTML template language. As such:
  * - The passed-in string should contain minimal HTML.
  * - Variable placeholders should not be used within the "<" and ">" of an
- *   HTML tag, such as in HTML attribute values; they are not safe for this
- *   purpose, and doing so represents a security risk:
+ *   HTML tag, such as in HTML attribute values, because this would be a
+ *   security risk. Examples:
  *   - Insecure: <@variable>text</@variable>
- *   - Insecure: <a href=":variable" title="@variable">link text</a>
+ *   - Insecure: <a @variable>link text</a>
+ *   - Insecure: <a title="@variable">link text</a>
  *   Only the "href" attribute is supported via the special ":variable"
  *   placeholder, to allow simple links to be inserted:
  *   - Secure: <a href=":variable">link text</a>
  *   - Secure: <a href=":variable" title="static text">link text</a>
- *   - Insecure: <a @variable>link text</a>
  *   - Insecure: <a href="@variable">link text</a>
- * For non-trivial HTML building that cannot meet the above restrictions, use
- * an HTML template language, such as Twig, rather than this function.
+ *   - Insecure: <a href=":variable" title="@variable">link text</a>
+ * To build HTML that cannot meet the above restrictions, use an HTML template
+ * language, such as Twig, rather than this function.
+ *
+ * See the documentation of
+ * \Drupal\Component\Utility\PlaceholderTrait::placeholderFormat() for
+ * details on the supported placeholders.
  *
  * @ingroup sanitization
  *