Issue #2501441 by mlncn, joelpittet, cilefen: Document SafeMarkup::set in AllowedTagsXssTrait::fieldFilterXss

core/lib/Drupal/Core/Field/AllowedTagsXssTrait.php

@@ -33,6 +33,15 @@ trait AllowedTagsXssTrait {
    *   valid UTF-8.
    */
   public function fieldFilterXss($string) {
+    // All known XSS vectors are filtered out by
+    // \Drupal\Component\Utility\Xss::filter(), all tags in the markup are
+    // allowed intentionally by the trait, and no danger is added in by
+    // \Drupal\Component\Utility\HTML::normalize(). Since the normalized value
+    // is essentially the same markup, designate this string as safe as well.
+    // This method is an internal part of field sanitization, so the resultant,
+    // sanitized string should be printable as is.
+    //
+    // @todo Free this memory in https://www.drupal.org/node/2505963.
     return SafeMarkup::set(Html::normalize(Xss::filter($string, $this->allowedTags())));
   }