commit 4432869706434832014d956e78e3db388c20d1e6
Author: xjm <xjm@65776.no-reply.drupal.org>
Date:   Sat Jul 12 15:04:14 2014 -0500

    Improve SafeMarkup docs a bit more.

diff --git a/core/lib/Drupal/Component/Utility/SafeMarkup.php b/core/lib/Drupal/Component/Utility/SafeMarkup.php
index d0e885d..d3844f0 100644
--- a/core/lib/Drupal/Component/Utility/SafeMarkup.php
+++ b/core/lib/Drupal/Component/Utility/SafeMarkup.php
@@ -10,14 +10,25 @@
 /**
  * Manages known safe strings for rendering at the theme layer.
  *
- * As Twig autoescapes string variables in the template, it is possible for a
- * string of markup to become double-escaped. SafeMarkup provides a store for
- * known safe strings and methods to manage them throughout the page request.
+ * The Twig theme engine autoescapes string variables in the template, so it
+ * is possible for a string of markup to become double-escaped. SafeMarkup
+ * provides a store for known safe strings and methods to manage them
+ * throughout the page request.
+ *
+ * Strings sanitized by String::checkPlain() or Xss::filter() are automatically
+ * marked safe, as are markup strings created from render arrays via
+ * drupal_render().
+ *
  * This class should be limited to interal use only. Module developers should
- * instead use render arrays or String::checkPlain() or Xss::filter() to
- * sanitize strings for output.
+ * instead use the appropriate
+ * @link sanitization sanitization functions @endlink or the
+ * @link theme_render theme and render systems @endlink so that the output can
+ * can be themed, escaped, and altered properly.
  *
+ * @see twig_drupal_escape_filter()
+ * @see twig_render_template()
  * @see sanitization
+ * @see theme_render
  */
 class SafeMarkup {