applies API conventions to the RDoc of json_encode

* Examples running with the text are preferred over separate Example
  sections.
* No need to call puts, in # => we show the return value, not STDOUT.
* Say explicitly that double quotes are removed.
* Specify that we are talking \uXXX, rather than, say, HTML entities.

1 files changed, 12 insertions, 10 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 37c206ea3c..bb0f747960 100644
--- a/activesupport/lib/active_support/core_ext/string/output_safety.rb
+++ b/activesupport/lib/active_support/core_ext/string/output_safety.rb
@@ -33,21 +33,23 @@ class ERB
     singleton_class.send(:remove_method, :html_escape)
     module_function :html_escape
 
-    # A utility method for escaping HTML entities in JSON strings.
-    # This method is also aliased as <tt>j</tt>.
+    # A utility method for escaping HTML entities in JSON strings
+    # using \uXXXX JavaScript escape sequences for string literals:
     #
-    # Note that after this operation is performed the output is not
-    # a valid JSON.
+    #   json_escape("is a > 0 & a < 10?")
+    #   # => is a \u003E 0 \u0026 a \u003C 10?
     #
-    # In your ERb templates, use this method to escape any HTML entities:
-    #   <%=j @person.to_json %>
+    # Note that after this operation is performed the output is not
+    # valid JSON. In particular double quotes are removed:
     #
-    # ==== Example:
-    #   puts json_escape("{\"name\":\"john\",\"created_at\":\"2010-04-28T01:39:31Z\",\"id\":1}")
+    #   json_escape('{"name":"john","created_at":"2010-04-28T01:39:31Z","id":1}')
     #   # => {name:john,created_at:2010-04-28T01:39:31Z,id:1}
     #
-    #   puts json_escape("is a > 0 & a < 10?")
-    #   # => is a \u003E 0 \u0026 a \u003C 10?
+    # This method is also aliased as +j+, and available as a helper
+    # in Rails templates:
+    #
+    #   <%=j @person.to_json %>
+    #
     def json_escape(s)
       s.to_s.gsub(/[&"><]/) { |special| JSON_ESCAPE[special] }
     end