diff --git a/core/lib/Drupal/Core/Render/Renderer.php b/core/lib/Drupal/Core/Render/Renderer.php
index bb8f1ff..0bc6be3 100644
--- a/core/lib/Drupal/Core/Render/Renderer.php
+++ b/core/lib/Drupal/Core/Render/Renderer.php
@@ -744,11 +744,11 @@ public function addCacheableDependency(array &$elements, $dependency) {
    * ensures that HTML intended for display is not filtered.
    *
    * @param string|\Drupal\Core\Render\SafeString $string
-   *   A string.
+   *   A string which will be sanitized if SafeMarkup::isSafe($string)
+   *   returns FALSE. Otherwise, it won't be sanitized again.
    *
    * @return \Drupal\Core\Render\SafeString
-   *   The escaped string wrapped in a SafeString object. If
-   *   SafeMarkup::isSafe($string) returns TRUE, it won't be escaped again.
+   *   The sanitized string wrapped in a SafeString object.
    */
   protected function xssFilterAdminIfUnsafe($string) {
     if (!SafeMarkup::isSafe($string)) {
@@ -765,24 +765,25 @@ protected function xssFilterAdminIfUnsafe($string) {
    * the render system needs to ensure that all markup it generates is marked
    * safe so that Twig does not do any additional escaping.
    *
-   * By default all #markup is filtered to protect against XSS using the admin
-   * tag list. Render arrays can alter the list of tags allowed by the filter
-   * using the #allowed_tags property. This value should be an array of tags
-   * that Xss::filter() would accept. Render arrays can escape text instead
-   * of XSS filtering by setting the #plain_text property instead of #markup. If
-   * #plain_text is used #allowed_tags is ignored.
+   * 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. 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 set.
+   *   A render array with #markup and/or #plain_text set. If both are set,
+   *   #plain_text takes precedence and #markup will be ignored.
    *
-   * @return \Drupal\Component\Utility\SafeStringInterface|string
-   *   The escaped markup wrapped in a SafeString object. If
-   *   SafeMarkup::isSafe($elements['#markup']) returns TRUE, it won't be
-   *   escaped or filtered again.
+   * @return array
+   *   A render array with #markup set where the sanitized markup is wrapped in a
+   *   SafeString object. If the contents of #markup are already in the
+   *   SafeMarkup::$safeStrings liststring, we'll retrn a string instead.
    *
    * @see \Drupal\Component\Utility\Html::escape()
    * @see \Drupal\Component\Utility\Xss::filter()
-   * @see \Drupal\Component\Utility\Xss::adminFilter()
+   * @see \Drupal\Component\Utility\Xss::filterAdmin()
    */
   protected function ensureMarkupIsSafe(array $elements) {
     if (empty($elements['#markup']) && empty($elements['#plain_text'])) {
diff --git a/core/lib/Drupal/Core/Render/theme.api.php b/core/lib/Drupal/Core/Render/theme.api.php
index e9144cf..dd01d16 100644
--- a/core/lib/Drupal/Core/Render/theme.api.php
+++ b/core/lib/Drupal/Core/Render/theme.api.php
@@ -270,17 +270,19 @@
  *   can customize the markup. Note that the value is passed through
  *   \Drupal\Component\Utility\Xss::filterAdmin(), which strips known XSS
  *   vectors while allowing a permissive list of HTML tags that are not XSS
- *   vectors. (I.e, <script> and <style> are not allowed.) See
+ *   vectors. (I.e., <script> and <style> are not allowed.) See
  *   \Drupal\Component\Utility\Xss::$adminTags for the list of tags that will
  *   be allowed. If your markup needs any of the tags that are not in this
  *   whitelist, then you can implement a theme hook and template file and/or
  *   an asset library. Aternatively, you can use the render array key
  *   #allowed_tags to alter which tags are filtered.
  * - #plain_text: Specifies that the array provides text that needs to be
- *   escaped. This value takes precedence over #markup if present.
+ *   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
- *   are using to filter the markup. The value should be an array of tags that
- *   Xss::filter() would accept. 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