update ActiveModel::Serializers documentation [ci skip]

2 files changed, 40 insertions, 14 deletions

diff --git a/activemodel/lib/active_model/serializers/json.rb b/activemodel/lib/active_model/serializers/json.rb
index ee888d3ee1..1894e21774 100644
--- a/activemodel/lib/active_model/serializers/json.rb
+++ b/activemodel/lib/active_model/serializers/json.rb
@@ -119,20 +119,22 @@ module ActiveModel
       #     end
       #   end
       #
+      #   json = { name: 'bob', age: 22, awesome:true }.to_json
       #   person = Person.new
-      #   person.from_json("{\"name\":\"bob\",\"age\":22,\"awesome\":true}")
-      #   person.name    # => "bob"
-      #   person.age     # => 22
-      #   person.awesome # => true
+      #   person.from_json(json) # => #<Person:0x007fec5e7a0088 @age=22, @awesome=true, @name="bob">
+      #   person.name            # => "bob"
+      #   person.age             # => 22
+      #   person.awesome         # => true
       #
       # The default value for +include_root+ is +false+. You can change it to
       # +true+ if the given JSON string includes a single root node.
       #
+      #   json = { person: { name: 'bob', age: 22, awesome:true } }.to_json
       #   person = Person.new
-      #   person.from_json("{\"person\":{\"name\":\"bob\",\"age\":22,\"awesome\":true}}", true)
-      #   person.name    # => "bob"
-      #   person.age     # => 22
-      #   person.awesome # => true
+      #   person.from_json(json) # => #<Person:0x007fec5e7a0088 @age=22, @awesome=true, @name="bob">
+      #   person.name            # => "bob"
+      #   person.age             # => 22
+      #   person.awesome         # => true
       def from_json(json, include_root=include_root_in_json)
         hash = ActiveSupport::JSON.decode(json)
         hash = hash.values.first if include_root
diff --git a/activemodel/lib/active_model/serializers/xml.rb b/activemodel/lib/active_model/serializers/xml.rb
index 2b3e9ce134..96ae47cec1 100644
--- a/activemodel/lib/active_model/serializers/xml.rb
+++ b/activemodel/lib/active_model/serializers/xml.rb
@@ -110,7 +110,7 @@ module ActiveModel
           end
         end
 
-        # TODO This can likely be cleaned up to simple use ActiveSupport::XmlMini.to_tag as well.
+        # TODO: This can likely be cleaned up to simple use ActiveSupport::XmlMini.to_tag as well.
         def add_associations(association, records, opts)
           merged_options = opts.merge(options.slice(:builder, :indent))
           merged_options[:skip_instruct] = true
@@ -161,8 +161,8 @@ module ActiveModel
       # Returns XML representing the model. Configuration can be
       # passed through +options+.
       #
-      # Without any +options+, the returned XML string will include all the model's
-      # attributes. For example:
+      # Without any +options+, the returned XML string will include all the
+      # model's attributes.
       #
       #   user = User.find(1)
       #   user.to_xml
@@ -175,18 +175,42 @@ module ActiveModel
       #     <created-at type="dateTime">2011-01-30T22:29:23Z</created-at>
       #   </user>
       #
-      # The <tt>:only</tt> and <tt>:except</tt> options can be used to limit the attributes
-      # included, and work similar to the +attributes+ method.
+      # The <tt>:only</tt> and <tt>:except</tt> options can be used to limit the
+      # attributes included, and work similar to the +attributes+ method.
       #
       # To include the result of some method calls on the model use <tt>:methods</tt>.
       #
       # To include associations use <tt>:include</tt>.
       #
-      # For further documentation see activerecord/lib/active_record/serializers/xml_serializer.xml.
+      # For further documentation, see activerecord/lib/active_record/serializers/xml_serializer.xml.
       def to_xml(options = {}, &block)
         Serializer.new(self, options).serialize(&block)
       end
 
+      # Sets the model +attributes+ from a JSON string. Returns +self+.
+      #
+      #   class Person
+      #     include ActiveModel::Serializers::Xml
+      #
+      #     attr_accessor :name, :age, :awesome
+      #
+      #     def attributes=(hash)
+      #       hash.each do |key, value|
+      #         instance_variable_set("@#{key}", value)
+      #       end
+      #     end
+      #
+      #     def attributes
+      #       instance_values
+      #     end
+      #   end
+      #
+      #   xml = { name: 'bob', age: 22, awesome:true }.to_xml
+      #   person = Person.new
+      #   person.from_xml(xml) # => #<Person:0x007fec5e3b3c40 @age=22, @awesome=true, @name="bob">
+      #   person.name          # => "bob"
+      #   person.age           # => 22
+      #   person.awesome       # => true
       def from_xml(xml)
         self.attributes = Hash.from_xml(xml).values.first
         self