update ActiveModel::Validations::Callbacks documentation [ci skip]

1 files changed, 69 insertions, 18 deletions

diff --git a/activemodel/lib/active_model/validations/callbacks.rb b/activemodel/lib/active_model/validations/callbacks.rb
index dbafd0bd1a..03a44a0e29 100644
--- a/activemodel/lib/active_model/validations/callbacks.rb
+++ b/activemodel/lib/active_model/validations/callbacks.rb
@@ -2,24 +2,24 @@ require 'active_support/callbacks'
 
 module ActiveModel
   module Validations
+    # == Active Model Validation callbacks
+    #
+    # Provides an interface for any class to have +before_validation+ and
+    # +after_validation+ callbacks.
+    #
+    # First, include ActiveModel::Validations::Callbacks from the class you are
+    # creating:
+    #
+    #   class MyModel
+    #     include ActiveModel::Validations::Callbacks
+    #
+    #     before_validation :do_stuff_before_validation
+    #     after_validation  :do_stuff_after_validation
+    #   end
+    #
+    # Like other <tt>before_*</tt> callbacks if +before_validation+ returns
+    # +false+ then <tt>valid?</tt> will not be called.
     module Callbacks
-      # == Active Model Validation callbacks
-      #
-      # Provides an interface for any class to have <tt>before_validation</tt> and
-      # <tt>after_validation</tt> callbacks.
-      #
-      # First, include ActiveModel::Validations::Callbacks from the class you are
-      # creating:
-      #
-      #   class MyModel
-      #     include ActiveModel::Validations::Callbacks
-      #
-      #     before_validation :do_stuff_before_validation
-      #     after_validation  :do_stuff_after_validation
-      #   end
-      #
-      #   Like other before_* callbacks if <tt>before_validation</tt> returns false
-      #   then <tt>valid?</tt> will not be called.
       extend ActiveSupport::Concern
 
       included do
@@ -28,6 +28,30 @@ module ActiveModel
       end
 
       module ClassMethods
+        # Defines a callback that will get called right before validation
+        # happens.
+        #
+        #   class Person
+        #     include ActiveModel::Validations
+        #     include ActiveModel::Validations::Callbacks
+        #
+        #     attr_accessor :name
+        #
+        #     validates_length_of :name, maximum: 6
+        #
+        #     before_validation :remove_whitespaces
+        #
+        #     private
+        #
+        #     def remove_whitespaces
+        #       name.strip!
+        #     end
+        #   end
+        #
+        #   person = Person.new
+        #   person.name = '  bob  '
+        #   person.valid? # => true
+        #   person.name   # => "bob"
         def before_validation(*args, &block)
           options = args.last
           if options.is_a?(Hash) && options[:on]
@@ -37,6 +61,33 @@ module ActiveModel
           set_callback(:validation, :before, *args, &block)
         end
 
+        # Defines a callback that will get called right after validation
+        # happens.
+        #
+        #   class Person
+        #     include ActiveModel::Validations
+        #     include ActiveModel::Validations::Callbacks
+        #
+        #     attr_accessor :name, :status
+        #
+        #     validates_presence_of :name
+        #
+        #     after_validation :set_status
+        #
+        #     private
+        #
+        #     def set_status
+        #       self.status = (errors.empty?) ? true : false
+        #     end
+        #   end
+        #
+        #   person = Person.new
+        #   person.name = ''
+        #   person.valid? # => false
+        #   person.status # => false
+        #   person.name = 'bob'
+        #   person.valid? # => true
+        #   person.status # => true
         def after_validation(*args, &block)
           options = args.extract_options!
           options[:prepend] = true
@@ -49,7 +100,7 @@ module ActiveModel
     protected
 
       # Overwrite run validations to include callbacks.
-      def run_validations!
+      def run_validations! #:nodoc:
         run_callbacks(:validation) { super }
       end
     end