diff -u b/core/lib/Drupal/Component/Utility/PlaceholderTrait.php b/core/lib/Drupal/Component/Utility/PlaceholderTrait.php
--- b/core/lib/Drupal/Component/Utility/PlaceholderTrait.php
+++ b/core/lib/Drupal/Component/Utility/PlaceholderTrait.php
@@ -16,10 +16,11 @@
    * Formats a string by replacing variable placeholders.
    *
    * This trait 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. Examples:
+   * 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. Examples:
    *   @code
    *     // Insecure (placeholder within "<" and ">"):
    *     $this->placeholderFormat('<@variable>text</@variable>', ['@variable' => $variable]);
@@ -36,8 +37,8 @@
    *     // Secure (usage of ":variable" placeholder for href attribute):
    *     $this->placeholderFormat('<a href=":variable" title="static text">link text</a>', [':variable' => $variable]);
    *     // Insecure (the "@variable" placeholder does not filter dangerous
-   *     // attributes):
-   *     $this->placeholderFormat('<a href="@variable">link text</a>', [':variable' => $variable]);
+   *     // protocols):
+   *     $this->placeholderFormat('<a href="@variable">link text</a>', ['@variable' => $variable]);
    *     // Insecure ("@variable" placeholder within "<" and ">"):
    *     $this->placeholderFormat('<a href=":url" title="@variable">link text</a>', [':url' => $url, '@variable' => $variable]);
    *   @endcode
@@ -56,20 +57,18 @@
    *   placeholder in $string. Sanitization and formatting will be done before
    *   replacement. The type of sanitization and formatting depends on the first
    *   character of the key:
-   *   - @variable: Use when the return value is to be used as HTML. When the
-   *     placeholder replacement value is:
-   *     - A string, it will be sanitized using
-   *       \Drupal\Component\Utility\Html::escape().
-   *     - A SafeStringInterface object, the object will be cast to a string and
-   *       not sanitized.
-   *     - A SafeStringInterface object cast to a string, forces sanitization.
-   *       Since it is not known what method a SafeStringInterface object could
-   *       have been santitized with, to force sanitization to happen, the
-   *       caller method could cast the object as a string before passing it in
-   *       as the replacement value.
-   *     Use this placeholder as the default choice for anything displayed on
-   *     the site, but not within HTML attributes, JavaScript, or CSS. Doing so
-   *     is a security risk.
+   *   - @variable: Use this placeholder as the default choice for anything
+   *     displayed on the site, but not within HTML attributes, JavaScript, or
+   *     CSS. Doing so is a security risk.
+   *     When the placeholder replacement value is:
+   *     - A string, the replaced value in the returned string will be sanitized
+   *       using \Drupal\Component\Utility\Html::escape().
+   *     - A SafeStringInterface object, the replacement will not be sanitized.
+   *     - A SafeStringInterface object cast to a string, the replacement will
+   *       be forcibly sanitized:
+   *       @code
+   *         $this->placeholderFormat('This will always be HTML-escaped: @text', ['@text' => (string) $safe_string_interface_object));
+   *       @endcode
    *   - %variable: Use when the return value is to be used inside HTML
    *     fragments similarly to @variable, but also wrapped in <em> tags. A call
    *     like:
@@ -87,8 +86,8 @@
    *   - :variable: Return value is escaped with
    *     \Drupal\Component\Utility\Html::escape() and filtered for dangerous
    *     protocols using UrlHelper::stripDangerousProtocols(). Use this when
-   *     using the "href" attribute, ensuring the value is always wrapped in
-   *     quotes:
+   *     using the "href" attribute, ensuring the attribute value is always
+   *     wrapped in quotes:
    *     @code
    *     // Secure (with quotes):
    *     $this->placeholderFormat('<a href=":url">@variable</a>', [':url' => $url, @variable => $variable]);