diff --git a/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php b/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php
index 82b76a0..c3fa5c6 100644
--- a/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php
+++ b/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php
@@ -13,12 +13,16 @@
 /**
  * Provides translatable markup class.
  *
- * This class delays translation until rendering.
+ * Formats a translatable string for HTML display by replacing variable
+ * placeholders. Handles an optional context for the string. This object, when
+ * cast to a string, will yield the translated string.
  *
  * This is useful for using translation in very low level subsystems like entity
  * definition and stream wrappers.
  *
- * @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
+ * This class delays translation until rendering.
+ *
+ * @see \Drupal\Component\Render\FormattableMarkup
  * @see \Drupal\Core\StringTranslation\TranslationManager::translate()
  * @see \Drupal\Core\StringTranslation\TranslationManager::translateString()
  * @see \Drupal\Core\Annotation\Translation
@@ -58,24 +62,75 @@ class TranslatableMarkup extends FormattableMarkup {
   /**
    * Constructs a new class instance.
    *
-   * Parses values passed into this class through the t() function in Drupal and
-   * handles an optional context for the string.
+   * If your class has a t(), use $this->t(), do not create this object. But, in
+   * a class that has t(), in a static method, create this object to do
+   * translation.
+   *
+   * Doing new TranslatableMarkup(), or calling the t() function, serves two
+   * purposes. First, at run-time it translates user-visible text into the
+   * appropriate language. Second, various mechanisms that figure out what text
+   * needs to be translated work off the string -- the text inside the call is
+   * added to the database of strings to be translated. These strings are
+   * expected to be in English, so the first argument should always be in
+   * English. To enable a fully-translatable site, it is important that all
+   * human-readable text that will be displayed on the site or sent to a user is
+   * passed through new TranslatableMarkup(), t(), or a related function. See
+   * the @link https://www.drupal.org/node/322729 Localization API @endlink
+   * pages for more information, including recommendations on how to break up or
+   * not break up strings for translation.
    *
    * @param string $string
-   *   The string that is to be translated.
+   *   A string containing the English string to translate.
    * @param array $arguments
-   *   (optional) An array with placeholder replacements, keyed by placeholder.
-   *   See \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
-   *   additional information about placeholders.
+   *   (optional) An associative array of replacements to make after
+   *   translation. Based on the first character of the key, the value is
+   *   escaped and/or themed. See
+   *   \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
+   *   details.
    * @param array $options
-   *   (optional) An array of additional options.
+   *   (optional) An associative array of additional options, with the following
+   *   elements:
+   *   - 'langcode' (defaults to the current language): The language code to
+   *     translate to a language other than what is used to display the page.
+   *   - 'context' (defaults to the empty context): The context the source
+   *     string belongs to.
    * @param \Drupal\Core\StringTranslation\TranslationInterface $string_translation
    *   (optional) The string translation service.
    *
    * @throws \InvalidArgumentException
    *   Exception thrown when $string is not a string.
    *
+   * @section sec_translating_vars Translating Variables
+   * $string should never just contain a variable, such as calling
+   * @code new TranslatableMarkup($text) @endcode for two reasons:
+   * - calling it on a variable that is user input is a security risk, and
+   * - calling it on a variable that has even guaranteed safe text, for example,
+   *   user interface text provided literally in code, will not be picked up by
+   *   the localization static text processor. (Unless the text that the
+   *   variable holds has been passed through t() elsewhere. But that strategy
+   *   is not recommended. It is better to call t() on literal strings.)
+   *
+   * It is especially important never to call new TranslatableMarkup($user_text)
+   * or t($user_text) where $user_text is some text that a user entered - doing
+   * that can lead to cross-site scripting and other security problems. However,
+   * you can use variable substitution in your string, to put variable text such
+   * as user names or link URLs into translated text. Variable substitution
+   * looks like this:
+   * @code
+   * new TranlsatableMarkup("@name's blog", array('@name' => $account->getDisplayName()));
+   * @endcode
+   * Basically, you can put variables like @name into your string, and it will
+   * substitute their sanitized values at translation time. (See the
+   * Localization API pages referenced above and the documentation of
+   * \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
+   * for details about how to safely and correctly define variables in your
+   * string.) Translators can then rearrange the string as necessary for the
+   * language (e.g., in Spanish, it might be "blog de @name").
+   *
    * @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
+   * @see \Drupal\Core\StringTranslation\StringTranslationTrait::t()
+   *
+   * @ingroup sanitization
    */
   public function __construct($string, array $arguments = array(), array $options = array(), TranslationInterface $string_translation = NULL) {
     if (!is_string($string)) {