diff -u b/core/lib/Drupal/Component/Utility/FormattableString.php b/core/lib/Drupal/Component/Utility/FormattableString.php
--- b/core/lib/Drupal/Component/Utility/FormattableString.php
+++ b/core/lib/Drupal/Component/Utility/FormattableString.php
@@ -25,12 +25,13 @@
  * directly is appropriate.
  *
  * This class is designed for formatting messages that are mostly text, not as
- * an HTML template language. As such, the passed-in string:
- * - Should contain minimal HTML.
- * - Should not be used within the "<" and ">" of an HTML tag, such as in HTML
- *   attribute values. This would be a security risk.
- * To build HTML that cannot meet these restrictions, use an HTML template
- * language such as Twig, rather than this class.
+ * an HTML template language. As such:
+ * - The passed in string should contain no (or minimal) HTML.
+ * - Variable placeholders should not be used within the "<" and ">" of an
+ *   HTML tag, such as in HTML attribute values. This would be a security
+ *   risk.
+ * To build non-minimal HTML, use an HTML template language such as Twig,
+ * rather than this class.
  *
  * @ingroup sanitization
  *