reverted:
--- b/core/lib/Drupal/Component/Utility/Html.php
+++ a/core/lib/Drupal/Component/Utility/Html.php
@@ -374,9 +374,9 @@
    * Html::decodeEntities() will convert all HTML entities to UTF-8 bytes,
    * including "&eacute;" and "&lt;" to "é" and "<".
    *
+   * When constructing @link theme_render render arrays @endlink passing the output of Html::escape() to
+   * '#markup' is not recommended. Use the '#plain_text' key instead and the
+   * renderer will autoescape the text.
-   * When constructing @link theme_render render arrays @endlink passing the
-   * output of Html::escape() to '#markup' is not recommended. Use the
-   * '#plain_text' key instead so that the renderer will autoescape the text.
    *
    * @param string $text
    *   The input text.
diff -u b/core/lib/Drupal/Core/Render/Renderer.php b/core/lib/Drupal/Core/Render/Renderer.php
--- b/core/lib/Drupal/Core/Render/Renderer.php
+++ b/core/lib/Drupal/Core/Render/Renderer.php
@@ -767,10 +767,10 @@
    *
    * By default all #markup is filtered using the admin tag list to protect
    * against XSS. Render arrays can alter the list of tags allowed by the filter
-   * by using the #allowed_tags property. This value should be an array of the
-   * tags that Xss::filter() must allow. Render arrays can escape text instead
-   * of XSS filtering by setting the #plain_text property instead of the
-   * #markup. If #plain_text is used #allowed_tags is ignored.
+   * by using the #allowed_tags property. If set, this value is an array of tags
+   * that will not be filtered from #markup by Xss::filter(). Render arrays can
+   * escape text instead of XSS filtering by setting the #plain_text property
+   * instead of the #markup. If #plain_text is used #allowed_tags is ignored.
    *
    * @param array $elements
    *   A render array with #markup and/or #plain_text set. If both are set,
diff -u b/core/lib/Drupal/Core/Render/theme.api.php b/core/lib/Drupal/Core/Render/theme.api.php
--- b/core/lib/Drupal/Core/Render/theme.api.php
+++ b/core/lib/Drupal/Core/Render/theme.api.php
@@ -280,8 +280,9 @@
  *   escaped. If #markup is set, #plain_text will take precedence and #markup
  *   will be ignored.
  * - #allowed_tags: If #markup is supplied this can be used to change which tags
- *   to use for filtering the markup. The value should be an array of the tags
- *   that Xss::filter() must allow. If #plain_text is set this value is ignored.
+ *   to use for filtering the markup. If set, this value is an array of tags
+ *   that will not be filtered from #markup by Xss::filter(). If #plain_text is
+ *   set this value is ignored.
  *
  *   Usage example:
  *   @code