Adding ActiveModel::Validations documentation

activemodel/README

@@ -175,4 +175,21 @@ functionality from the following modules:
     end
   
   {Learn more}[link:classes/ActiveModel/Translation.html]
-  
+
+* Providing a full Validation stack for your objects...
+
+   class Person
+     include ActiveModel::Validations
+
+     attr_accessor :first_name, :last_name
+
+     validates_each :first_name, :last_name do |record, attr, value|
+       record.errors.add attr, 'starts with z.' if value.to_s[0] == ?z
+     end
+   end
+
+   person = Person.new(:first_name => 'zoolander')
+   person.valid?          #=> false
+
+  {Learn more}[link:classes/ActiveModel/Validations.html]
+  

activemodel/lib/active_model/validations.rb

@@ -3,6 +3,41 @@ require 'active_support/core_ext/hash/keys'
 require 'active_model/errors'
 
 module ActiveModel
+  
+  # Provides a full validation framework to your objects.
+  # 
+  # A minimal implementation could be:
+  # 
+  #   class Person
+  #     include ActiveModel::Validations
+  # 
+  #     attr_accessor :first_name, :last_name
+  #
+  #     validates_each :first_name, :last_name do |record, attr, value|
+  #       record.errors.add attr, 'starts with z.' if value.to_s[0] == ?z
+  #     end
+  #   end
+  # 
+  # Which provides you with the full standard validation stack that you
+  # know from ActiveRecord.
+  # 
+  #   person = Person.new
+  #   person.valid?
+  #   #=> true
+  #   person.invalid?
+  #   #=> false
+  #   person.first_name = 'zoolander'
+  #   person.valid?         
+  #   #=> false
+  #   person.invalid?
+  #   #=> true
+  #   person.errors
+  #   #=> #<OrderedHash {:first_name=>["starts with z."]}>
+  # 
+  # Note that ActiveModel::Validations automatically adds an +errors+ method
+  # to your instances initialized with a new ActiveModel::Errors object, so
+  # there is no need for you to add this manually.
+  # 
   module Validations
     extend ActiveSupport::Concern
     include ActiveSupport::Callbacks
@@ -18,8 +53,10 @@ module ActiveModel
       #   class Person
       #     include ActiveModel::Validations
       # 
+      #     attr_accessor :first_name, :last_name
+      #
       #     validates_each :first_name, :last_name do |record, attr, value|
-      #       record.errors.add attr, 'starts with z.' if value[0] == ?z
+      #       record.errors.add attr, 'starts with z.' if value.to_s[0] == ?z
       #     end
       #   end
       #