update ActiveModel::Dirty documentation

1 files changed, 35 insertions, 24 deletions

diff --git a/activemodel/lib/active_model/dirty.rb b/activemodel/lib/active_model/dirty.rb
index 3f2fd12db7..7014d8114f 100644
--- a/activemodel/lib/active_model/dirty.rb
+++ b/activemodel/lib/active_model/dirty.rb
@@ -11,14 +11,14 @@ module ActiveModel
   #
   # The requirements for implementing ActiveModel::Dirty are:
   #
-  # * <tt>include ActiveModel::Dirty</tt> in your object
+  # * <tt>include ActiveModel::Dirty</tt> in your object.
   # * Call <tt>define_attribute_methods</tt> passing each method you want to
-  #   track
+  #   track.
   # * Call <tt>attr_name_will_change!</tt> before each change to the tracked
-  #   attribute
+  #   attribute.
   #
   # If you wish to also track previous changes on save or update, you need to
-  # add
+  # add:
   #
   #   @previously_changed = changes
   #
@@ -27,7 +27,6 @@ module ActiveModel
   # A minimal implementation could be:
   #
   #   class Person
-  #
   #     include ActiveModel::Dirty
   #
   #     define_attribute_methods :name
@@ -45,47 +44,49 @@ module ActiveModel
   #       @previously_changed = changes
   #       @changed_attributes.clear
   #     end
-  #
   #   end
   #
-  # == Examples:
-  #
   # A newly instantiated object is unchanged:
+  #
   #   person = Person.find_by_name('Uncle Bob')
   #   person.changed?       # => false
   #
   # Change the name:
+  #
   #   person.name = 'Bob'
   #   person.changed?       # => true
   #   person.name_changed?  # => true
-  #   person.name_was       # => 'Uncle Bob'
-  #   person.name_change    # => ['Uncle Bob', 'Bob']
+  #   person.name_was       # => "Uncle Bob"
+  #   person.name_change    # => ["Uncle Bob", "Bob"]
   #   person.name = 'Bill'
-  #   person.name_change    # => ['Uncle Bob', 'Bill']
+  #   person.name_change    # => ["Uncle Bob", "Bill"]
   #
   # Save the changes:
+  #
   #   person.save
   #   person.changed?       # => false
   #   person.name_changed?  # => false
   #
   # Assigning the same value leaves the attribute unchanged:
+  #
   #   person.name = 'Bill'
   #   person.name_changed?  # => false
   #   person.name_change    # => nil
   #
   # Which attributes have changed?
+  #
   #   person.name = 'Bob'
-  #   person.changed        # => ['name']
-  #   person.changes        # => { 'name' => ['Bill', 'Bob'] }
+  #   person.changed        # => ["name"]
+  #   person.changes        # => {"name" => ["Bill", "Bob"]}
   #
   # If an attribute is modified in-place then make use of <tt>[attribute_name]_will_change!</tt>
   # to mark that the attribute is changing. Otherwise ActiveModel can't track changes to
   # in-place attributes.
   #
   #   person.name_will_change!
-  #   person.name_change    # => ['Bill', 'Bill']
+  #   person.name_change    # => ["Bill", "Bill"]
   #   person.name << 'y'
-  #   person.name_change    # => ['Bill', 'Billy']
+  #   person.name_change    # => ["Bill", "Billy"]
   module Dirty
     extend ActiveSupport::Concern
     include ActiveModel::AttributeMethods
@@ -95,7 +96,8 @@ module ActiveModel
       attribute_method_affix :prefix => 'reset_', :suffix => '!'
     end
 
-    # Returns true if any attribute have unsaved changes, false otherwise.
+    # Returns +true+ if any attribute have unsaved changes, +false+ otherwise.
+    #
     #   person.changed? # => false
     #   person.name = 'bob'
     #   person.changed? # => true
@@ -103,32 +105,41 @@ module ActiveModel
       changed_attributes.present?
     end
 
-    # List of attributes with unsaved changes.
+    # Returns an array with the name of the attributes with unsaved changes.
+    #
     #   person.changed # => []
     #   person.name = 'bob'
-    #   person.changed # => ['name']
+    #   person.changed # => ["name"]
     def changed
       changed_attributes.keys
     end
 
-    # Map of changed attrs => [original value, new value].
+    # Returns a hash of changed attributes indicating their original
+    # and new values like <tt>attr => [original value, new value]</tt>. 
+    #
     #   person.changes # => {}
     #   person.name = 'bob'
-    #   person.changes # => { 'name' => ['bill', 'bob'] }
+    #   person.changes # => { "name" => ["bill", "bob"] }
     def changes
       HashWithIndifferentAccess[changed.map { |attr| [attr, attribute_change(attr)] }]
     end
 
-    # Map of attributes that were changed when the model was saved.
-    #   person.name # => 'bob'
+    # Returns a hash of attributes that were changed before the model was saved.
+    #
+    #   person.name # => "bob"
     #   person.name = 'robert'
     #   person.save
-    #   person.previous_changes # => {'name' => ['bob, 'robert']}
+    #   person.previous_changes # => {"name" => ["bob", "robert"]}
     def previous_changes
       @previously_changed
     end
 
-    # Map of change <tt>attr => original value</tt>.
+    # Returns a hash of the attributes with unsaved changes indicating their original
+    # values like <tt>attr => original value</tt>.
+    #
+    #   person.name # => "bob"
+    #   person.name = 'robert'
+    #   person.changed_attributes # => {"name" => "bob"}
     def changed_attributes
       @changed_attributes ||= {}
     end