2 files changed, 13 insertions, 6 deletions
diff --git a/activemodel/lib/active_model/secure_password.rb b/activemodel/lib/active_model/secure_password.rb
index ff2213231f..8711b24124 100644
--- a/activemodel/lib/active_model/secure_password.rb
+++ b/activemodel/lib/active_model/secure_password.rb
@@ -58,7 +58,8 @@ module ActiveModel
         BCrypt::Password.new(password_digest) == unencrypted_password && self
       end
 
-      # Encrypts the password into the password_digest attribute.
+      # Encrypts the password into the password_digest attribute, only if the
+      # new password is not blank.
       def password=(unencrypted_password)
         unless unencrypted_password.blank?
           @password = unencrypted_password
diff --git a/activemodel/lib/active_model/serialization.rb b/activemodel/lib/active_model/serialization.rb
index 06bedf1c47..a5828476b1 100644
--- a/activemodel/lib/active_model/serialization.rb
+++ b/activemodel/lib/active_model/serialization.rb
@@ -26,17 +26,18 @@ module ActiveModel
   #   person.serializable_hash   # => {"name"=>"Bob"}
   #
   # You need to declare an attributes hash which contains the attributes
-  # you want to serialize. When called, serializable hash will use
+  # 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.
+  # 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
-  # ActiveModel::Serialization module, so there is no need to explicitly
+  # +ActiveModel::Serialization+ module, so there is no need to explicitly
   # include it.
   #
-  # So a minimal implementation including XML and JSON would be:
+  # A minimal implementation including XML and JSON would be:
   #
   #   class Person
   #     include ActiveModel::Serializers::JSON
@@ -63,7 +64,12 @@ 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> and <tt>:methods</tt> .
+  # 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' }})
   module Serialization
     def serializable_hash(options = nil)
       options ||= {}