update ActiveModel::Serialization documentation [ci skip]

1 files changed, 36 insertions, 14 deletions

diff --git a/activemodel/lib/active_model/serialization.rb b/activemodel/lib/active_model/serialization.rb
index 6d8fd21814..8a63014ffb 100644
--- a/activemodel/lib/active_model/serialization.rb
+++ b/activemodel/lib/active_model/serialization.rb
@@ -25,17 +25,16 @@ module ActiveModel
   #   person.name = "Bob"
   #   person.serializable_hash   # => {"name"=>"Bob"}
   #
-  # You need to declare an attributes hash which contains the attributes
-  # you want to serialize. Attributes must be strings, not symbols.
-  # When called, serializable hash will use
-  # instance methods that match the name of the attributes hash's keys.
-  # In order to override this behavior, take a look at the private
-  # method +read_attribute_for_serialization+.
+  # You need to declare an attributes hash which contains the attributes you
+  # want to serialize. Attributes must be strings, not symbols. When called,
+  # serializable hash will use instance methods that match the name of the
+  # attributes hash's keys. In order to override this behavior, take a look at
+  # the private method +read_attribute_for_serialization+.
   #
   # Most of the time though, you will want to include the JSON or XML
   # serializations. Both of these modules automatically include the
-  # <tt>ActiveModel::Serialization</tt> module, so there is no need to explicitly
-  # include it.
+  # <tt>ActiveModel::Serialization</tt> module, so there is no need to
+  # explicitly include it.
   #
   # A minimal implementation including XML and JSON would be:
   #
@@ -64,13 +63,37 @@ module ActiveModel
   #   person.to_json             # => "{\"name\":\"Bob\"}"
   #   person.to_xml              # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<serial-person...
   #
-  # Valid options are <tt>:only</tt>, <tt>:except</tt>, <tt>:methods</tt> and <tt>:include</tt>.
-  # The following are all valid examples:
+  # Valid options are <tt>:only</tt>, <tt>:except</tt>, <tt>:methods</tt> and
+  # <tt>:include</tt>. The following are all valid examples:
   #
-  #   person.serializable_hash(:only => 'name')
-  #   person.serializable_hash(:include => :address)
-  #   person.serializable_hash(:include => { :address => { :only => 'city' }})
+  #   person.serializable_hash(only: 'name')
+  #   person.serializable_hash(include: :address)
+  #   person.serializable_hash(include: { address: { only: 'city' }})
   module Serialization
+    # Returns a serialized hash of your object.
+    #
+    #   class Person
+    #     include ActiveModel::Serialization
+    #
+    #     attr_accessor :name, :age
+    #
+    #     def attributes
+    #       {'name' => nil, 'age' => nil}
+    #     end
+    #
+    #     def capitalized_name
+    #       name.capitalize
+    #     end
+    #   end
+    #
+    #   person = Person.new
+    #   person.name = 'bob'
+    #   person.age  = 22
+    #   person.serializable_hash                # => {"name"=>"bob", "age"=>22}
+    #   person.serializable_hash(only: :name)   # => {"name"=>"bob"}
+    #   person.serializable_hash(except: :name) # => {"age"=>22}
+    #   person.serializable_hash(methods: :capitalized_name)
+    #   # => {"name"=>"bob", "age"=>22, "capitalized_name"=>"Bob"}
     def serializable_hash(options = nil)
       options ||= {}
 
@@ -115,7 +138,6 @@ module ActiveModel
       #       @data[key]
       #     end
       #   end
-      #
       alias :read_attribute_for_serialization :send
 
       # Add associations specified via the <tt>:include</tt> option.