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.
+ # ActiveModel::Dirty provides a way to track changes in your
+ # object in the same way as ActiveRecord does.
+ #
+ # The requirements to implement ActiveModel::Dirty are:
+ #
+ # * include ActiveModel::Dirty in your object
+ # * Call define_attribute_methods passing each method you want to track
+ # * Call attr_name_will_change! 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')