1 files changed, 29 insertions, 12 deletions
diff --git a/activemodel/README.rdoc b/activemodel/README.rdoc
index 9208145507..9b05384792 100644
--- a/activemodel/README.rdoc
+++ b/activemodel/README.rdoc
@@ -9,10 +9,31 @@ Prior to Rails 3.0, if a plugin or gem developer wanted to have an object
 interact with Action Pack helpers, it was required to either copy chunks of
 code from Rails, or monkey patch entire helpers to make them handle objects
 that did not exactly conform to the Active Record interface. This would result
-in code duplication and fragile applications that broke on upgrades.
+in code duplication and fragile applications that broke on upgrades. Active
+Model solves this by defining an explicit API. You can read more about the
+API in ActiveModel::Lint::Tests.
 
-Active Model solves this. You can include functionality from the following
-modules:
+Active Model provides a default module that implements the basic API required
+to integrate with Action Pack out of the box: <tt>ActiveModel::Model</tt>.
+
+    class Person
+      include ActiveModel::Model
+
+      attr_accessor :name, :age
+      validates_presence_of :name
+    end
+
+    person = Person.new(:name => 'bob', :age => '18')
+    person.name # => 'bob'
+    person.age # => 18
+    person.valid? # => true
+
+It includes model name introspections, conversions, translations and
+validations, resulting in a class suitable to be used with Action Pack.
+See <tt>ActiveModel::Model</tt> for more examples.
+
+Active Model also provides the following functionality to have ORM-like
+behavior out of the box:
 
 * Add attribute magic to objects
 
@@ -50,7 +71,7 @@ modules:
   This generates +before_create+, +around_create+ and +after_create+
   class methods that wrap your create method.
 
-  {Learn more}[link:classes/ActiveModel/CallBacks.html]
+  {Learn more}[link:classes/ActiveModel/Callbacks.html]
 
 * Tracking value changes
 
@@ -87,18 +108,14 @@ modules:
         errors.add(:name, "can not be nil") if name.nil?
       end
 
-      def ErrorsPerson.human_attribute_name(attr, options = {})
+      def self.human_attribute_name(attr, options = {})
         "Name"
       end
-
     end
 
     person.errors.full_messages
     # => ["Name can not be nil"]
 
-    person.errors.full_messages
-    # => ["Name can not be nil"]
-
   {Learn more}[link:classes/ActiveModel/Errors.html]
 
 * Model name introspection
@@ -163,7 +180,7 @@ modules:
 
 * Custom validators
 
-   class Person
+   class ValidatorPerson
      include ActiveModel::Validations
      validates_with HasNameValidator
      attr_accessor :name
@@ -171,7 +188,7 @@ modules:
 
    class HasNameValidator < ActiveModel::Validator
      def validate(record)
-      record.errors[:name] = "must exist" if record.name.blank?
+       record.errors[:name] = "must exist" if record.name.blank?
      end
    end
 
@@ -182,7 +199,7 @@ modules:
    p.valid?                  # =>  true
 
   {Learn more}[link:classes/ActiveModel/Validator.html]
-  
+
 
 == Download and installation