1 files changed, 17 insertions, 3 deletions
diff --git a/activerecord/lib/active_record/validations.rb b/activerecord/lib/active_record/validations.rb
index f367315b22..d73fce9fd0 100644
--- a/activerecord/lib/active_record/validations.rb
+++ b/activerecord/lib/active_record/validations.rb
@@ -1,5 +1,5 @@
 module ActiveRecord
-  # = Active Record Validations
+  # = Active Record RecordInvalid
   #
   # Raised by <tt>save!</tt> and <tt>create!</tt> when the record is invalid.  Use the
   # +record+ method to retrieve the record which did not validate.
@@ -18,6 +18,13 @@ module ActiveRecord
     end
   end
 
+  # = Active Record Validations
+  #
+  # Active Record includes the majority of its validations from <tt>ActiveModel::Validations</tt>
+  # all of which accept the <tt>:on</tt> argument to define the context where the
+  # validations are active. Active Record will always supply either the context of
+  # <tt>:create</tt> or <tt>:update</tt> dependent on whether the model is a
+  # <tt>new_record?</tt>.
   module Validations
     extend ActiveSupport::Concern
     include ActiveModel::Validations
@@ -37,7 +44,7 @@ module ActiveRecord
       end
     end
 
-    # The validation process on save can be skipped by passing false. The regular Base#save method is
+    # The validation process on save can be skipped by passing :validate => false. The regular Base#save method is
     # replaced with this when the validations module is mixed in, which it is by default.
     def save(options={})
       perform_validations(options) ? super : false
@@ -49,7 +56,14 @@ module ActiveRecord
       perform_validations(options) ? super : raise(RecordInvalid.new(self))
     end
 
-    # Runs all the specified validations and returns true if no errors were added otherwise false.
+    # Runs all the validations within the specified context. Returns true if no errors are found,
+    # false otherwise.
+    #
+    # If the argument is false (default is +nil+), the context is set to <tt>:create</tt> if
+    # <tt>new_record?</tt> is true, and to <tt>:update</tt> if it is not.
+    #
+    # Validations with no <tt>:on</tt> option will run no matter the context. Validations with
+    # some <tt>:on</tt> option will only run in the specified context.
     def valid?(context = nil)
       context ||= (new_record? ? :create : :update)
       output = super(context)