diff --git a/core/lib/Drupal/Core/Utility/Token.php b/core/lib/Drupal/Core/Utility/Token.php
index a62a59f..1e65620 100644
--- a/core/lib/Drupal/Core/Utility/Token.php
+++ b/core/lib/Drupal/Core/Utility/Token.php
@@ -19,6 +19,7 @@
 use Drupal\Core\Render\AttachmentsInterface;
 use Drupal\Core\Render\BubbleableMetadata;
 use Drupal\Core\Render\RendererInterface;
+use Drupal\Core\Render\SafeString;
 
 /**
  * Drupal placeholder/token replacement system.
@@ -205,11 +206,6 @@ public function replace($text, array $data = array(), array $options = array(),
       }
     }
 
-    // Escape the tokens, unless they are explicitly markup.
-    foreach ($replacements as $token => $value) {
-      $replacements[$token] = SafeMarkup::isSafe($value) ? $value : Html::escape($value);
-    }
-
     // Optionally alter the list of replacement values.
     if (!empty($options['callback'])) {
       $function = $options['callback'];
@@ -268,6 +264,12 @@ public function scan($text) {
   /**
    * Generates replacement values for a list of tokens.
    *
+   * Typically, application code does not invoke this function directly, but
+   * rather invokes the replace() function, and this gets called via that.
+   * However, application code that wants to retrieve token values in isolation
+   * rather than merged into a string with token placeholders may use this
+   * function to do so.
+   *
    * @param string $type
    *   The type of token being replaced. 'node', 'user', and 'date' are common.
    * @param array $tokens
@@ -284,18 +286,22 @@ public function scan($text) {
    *   process. Supported options are:
    *   - langcode: A language code to be used when generating locale-sensitive
    *     tokens.
-   *   - callback: A callback function that will be used to post-process the
-   *     array of token replacements after they are generated. Can be used when
-   *     modules require special formatting of token text, for example URL
-   *     encoding or truncation to a specific length.
    * @param \Drupal\Core\Render\BubbleableMetadata $bubbleable_metadata
    *    The bubbleable metadata. This is passed to the token replacement
    *    implementations so that they can attach their metadata.
    *
    * @return array
    *   An associative array of replacement values, keyed by the original 'raw'
-   *   tokens that were found in the source text. For example:
-   *   $results['[node:title]'] = 'My new node';
+   *   tokens that were found in the source text. Each value is a
+   *   \Drupal\Component\Utility\SafeStringInterface object, meaning that it
+   *   is encoded and sanitized for HTML, and will therefore not be escaped by
+   *   Twig's autoescaping. If the caller wants to use a token value in
+   *   plain-text context, such as an email subject, it can convert it to
+   *   plain-text by using PlainTextOutput::renderFromHtml(). For example:
+   *   @code
+   *     $token_values = $token_service->generate('node', ['title' => '[node:title]'], $options, $bubbleable_metadata);
+   *     $email_subject = PlainTextOutput::renderFromHtml($token_values['[node:title]']);
+   *   @endcode
    *
    * @see hook_tokens()
    * @see hook_tokens_alter()
@@ -318,6 +324,11 @@ public function generate($type, array $tokens, array $data, array $options, Bubb
     );
     $this->moduleHandler->alter('tokens', $replacements, $context, $bubbleable_metadata);
 
+    // Escape the tokens, unless they are explicitly markup.
+    foreach ($replacements as $token => $value) {
+      $replacements[$token] = SafeMarkup::isSafe($value) ? $value : SafeString::create(Html::escape($value));
+    }
+
     return $replacements;
   }
 
