Document `String#html_safe` [ci skip]

It should be part of the documented public API, since we have an entire
section of the guides dedicated to it. Documented in a way that
addresses the concerns which kept it undocumented in the past.

1 files changed, 5 insertions, 0 deletions

diff --git a/activesupport/lib/active_support/core_ext/string/output_safety.rb b/activesupport/lib/active_support/core_ext/string/output_safety.rb
index 042283e4fc..ba92afd5f4 100644
--- a/activesupport/lib/active_support/core_ext/string/output_safety.rb
+++ b/activesupport/lib/active_support/core_ext/string/output_safety.rb
@@ -247,6 +247,11 @@ module ActiveSupport #:nodoc:
 end
 
 class String
+  # Marks a string as trusted safe. It will be inserted into HTML with no
+  # additional escaping performed. It is your responsibilty to ensure that the
+  # string contains no malicious content. This method is equivalent to the
+  # `raw` helper in views. It is recommended that you use `sanitize` instead of
+  # this method. It should never be called on user input.
   def html_safe
     ActiveSupport::SafeBuffer.new(self)
   end