describe action of include_root_in_json in to_json docs

1 files changed, 19 insertions, 0 deletions

diff --git a/activerecord/lib/active_record/serializers/json_serializer.rb b/activerecord/lib/active_record/serializers/json_serializer.rb
index 419b45d475..1fd65ed006 100644
--- a/activerecord/lib/active_record/serializers/json_serializer.rb
+++ b/activerecord/lib/active_record/serializers/json_serializer.rb
@@ -8,6 +8,25 @@ module ActiveRecord #:nodoc:
     # Returns a JSON string representing the model. Some configuration is
     # available through +options+.
     #
+    # The option <tt>ActiveRecord::Base.include_root_in_json</tt> controls the
+    # top-level behavior of to_json. In a new Rails application, it is set to 
+    # <tt>true</tt> in initializers/new_rails_defaults.rb. When it is <tt>true</tt>,
+    # to_json will emit a single root node named after the object's type. For example:
+    #
+    #   konata = User.find(1)
+    #   ActiveRecord::Base.include_root_in_json = true
+    #   konata.to_json
+    #   # => { "user": {"id": 1, "name": "Konata Izumi", "age": 16,
+    #                   "created_at": "2006/08/01", "awesome": true} }
+    #
+    #   ActiveRecord::Base.include_root_in_json = false
+    #   konata.to_json
+    #   # => {"id": 1, "name": "Konata Izumi", "age": 16,
+    #         "created_at": "2006/08/01", "awesome": true}
+    #
+    # The remainder of the examples in this section assume include_root_in_json is set to
+    # <tt>false</tt>.
+    #
     # Without any +options+, the returned JSON string will include all
     # the model's attributes. For example:
     #