Adding RDoc for active_model dirty

2 files changed, 44 insertions, 27 deletions

diff --git a/activemodel/README b/activemodel/README
index 0c558ed85a..7c9c754a8e 100644
--- a/activemodel/README
+++ b/activemodel/README
@@ -9,9 +9,8 @@ duplication and fragile applications that broke on upgrades.
 Active Model is a solution for this problem.
 
 Active Model provides a known set of interfaces that your objects can implement
-to then present a common interface to the Action Pack helpers.
-
-You can include functionality from the following modules:
+to then present a common interface to the Action Pack helpers.  You can include
+functionality from the following modules:
 
 * Adding callbacks to your class
 
@@ -41,28 +40,7 @@ You can include functionality from the following modules:
 
 * Tracking changes in your object
 
-    class Person
-      include ActiveModel::Dirty
-
-      define_attribute_methods [:name]
-
-      def name
-        @name
-      end
-
-      def name=(val)
-        name_will_change!
-        @name = val
-      end
-      
-      def save
-        @previously_changed = changes
-        true
-      end
-      
-    end
-    
-    ...provides all the value tracking features implemented by ActiveRecord
+    Provides all the value tracking features implemented by ActiveRecord...
     
     person = Person.new
     person.name # => nil
@@ -75,4 +53,5 @@ You can include functionality from the following modules:
     person.save
     person.previous_changes # => {'name' => ['bob, 'robert']}
 
-    {Learn more}[link:classes/ActiveModel/Dirty.html]
+  {Learn more}[link:classes/ActiveModel/Dirty.html]
+
diff --git a/activemodel/lib/active_model/dirty.rb b/activemodel/lib/active_model/dirty.rb
index 735c61df74..5f02929a9d 100644
--- a/activemodel/lib/active_model/dirty.rb
+++ b/activemodel/lib/active_model/dirty.rb
@@ -1,5 +1,43 @@
 module ActiveModel
-  # Track unsaved attribute changes.
+  # <tt>ActiveModel::Dirty</tt> provides a way to track changes in your
+  # object in the same way as ActiveRecord does.
+  # 
+  # The requirements to implement ActiveModel::Dirty are:
+  #
+  # * <tt>include ActiveModel::Dirty</tt> in your object
+  # * Call <tt>define_attribute_methods</tt> passing each method you want to track
+  # * Call <tt>attr_name_will_change!</tt> before each change to the tracked attribute
+  # 
+  # If you wish to also track previous changes on save or update, you need to add
+  # 
+  #   @previously_changed = changes
+  # 
+  # inside of your save or update method.
+  # 
+  # A minimal implementation could be:
+  # 
+  #   class Person
+  #   
+  #     include ActiveModel::Dirty
+  #   
+  #     define_attribute_methods [:name]
+  #   
+  #     def name
+  #       @name
+  #     end
+  #   
+  #     def name=(val)
+  #       name_will_change!
+  #       @name = val
+  #     end
+  #   
+  #     def save
+  #       @previously_changed = changes
+  #     end
+  #   
+  #   end
+  # 
+  # == Examples:
   #
   # A newly instantiated object is unchanged:
   #   person = Person.find_by_name('Uncle Bob')