Merge branch 'master' of github.com:lifo/docrails

Conflicts:
	activemodel/lib/active_model/secure_password.rb
	activerecord/lib/active_record/associations/collection_proxy.rb

3 files changed, 130 insertions, 65 deletions

diff --git a/activemodel/lib/active_model/validations/callbacks.rb b/activemodel/lib/active_model/validations/callbacks.rb
index dbafd0bd1a..bf3fe7ff04 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?
+        #     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
diff --git a/activemodel/lib/active_model/validations/validates.rb b/activemodel/lib/active_model/validations/validates.rb
index ecda9dffcf..5892ad29d1 100644
--- a/activemodel/lib/active_model/validations/validates.rb
+++ b/activemodel/lib/active_model/validations/validates.rb
@@ -11,18 +11,18 @@ module ActiveModel
       #
       # Examples of using the default rails validators:
       #
-      #   validates :terms, :acceptance => true
-      #   validates :password, :confirmation => true
-      #   validates :username, :exclusion => { :in => %w(admin superuser) }
-      #   validates :email, :format => { :with => /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\Z/i, :on => :create }
-      #   validates :age, :inclusion => { :in => 0..9 }
-      #   validates :first_name, :length => { :maximum => 30 }
-      #   validates :age, :numericality => true
-      #   validates :username, :presence => true
-      #   validates :username, :uniqueness => true
+      #   validates :terms, acceptance: true
+      #   validates :password, confirmation: true
+      #   validates :username, exclusion: { in: %w(admin superuser) }
+      #   validates :email, format: { with: /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\Z/i, on: :create }
+      #   validates :age, inclusion: { in: 0..9 }
+      #   validates :first_name, length: { maximum: 30 }
+      #   validates :age, numericality: true
+      #   validates :username, presence: true
+      #   validates :username, uniqueness: true
       #
       # The power of the +validates+ method comes when using custom validators
-      # and default validators in one call for a given attribute e.g.
+      # and default validators in one call for a given attribute.
       #
       #   class EmailValidator < ActiveModel::EachValidator
       #     def validate_each(record, attribute, value)
@@ -35,12 +35,12 @@ module ActiveModel
       #     include ActiveModel::Validations
       #     attr_accessor :name, :email
       #
-      #     validates :name, :presence => true, :uniqueness => true, :length => { :maximum => 100 }
-      #     validates :email, :presence => true, :email => true
+      #     validates :name, presence: true, uniqueness: true, length: { maximum: 100 }
+      #     validates :email, presence: true, email: true
       #   end
       #
       # Validator classes may also exist within the class being validated
-      # allowing custom modules of validators to be included as needed e.g.
+      # allowing custom modules of validators to be included as needed.
       #
       #   class Film
       #     include ActiveModel::Validations
@@ -51,25 +51,27 @@ module ActiveModel
       #       end
       #     end
       #
-      #     validates :name, :title => true
+      #     validates :name, title: true
       #   end
       #
-      # Additionally validator classes may be in another namespace and still used within any class.
+      # Additionally validator classes may be in another namespace and still
+      # used within any class.
       #
       #   validates :name, :'film/title' => true
       #
-      # The validators hash can also handle regular expressions, ranges,
-      # arrays and strings in shortcut form, e.g.
+      # The validators hash can also handle regular expressions, ranges, arrays
+      # and strings in shortcut form.
       #
-      #   validates :email, :format => /@/
-      #   validates :gender, :inclusion => %w(male female)
-      #   validates :password, :length => 6..20
+      #   validates :email, format: /@/
+      #   validates :gender, inclusion: %w(male female)
+      #   validates :password, length: 6..20
       #
       # When using shortcut form, ranges and arrays are passed to your
-      # validator's initializer as +options[:in]+ while other types including
-      # regular expressions and strings are passed as +options[:with]+
+      # validator's initializer as <tt>options[:in]</tt> while other types
+      # including regular expressions and strings are passed as <tt>options[:with]</tt>.
       #
       # There is also a list of options that could be used along with validators:
+      #
       # * <tt>:on</tt> - Specifies when this validation is active. Runs in all
       #   validation contexts by default (+nil+), other options are <tt>:create</tt>
       #   and <tt>:update</tt>.
@@ -87,14 +89,12 @@ module ActiveModel
       #
       # Example:
       #
-      #   validates :password, :presence => true, :confirmation => true, :if => :password_required?
-      #
-      # Finally, the options +:if+, +:unless+, +:on+, +:allow_blank+, +:allow_nil+ and +:strict+
-      # can be given to one specific validator, as a hash:
-      #
-      #   validates :password, :presence => { :if => :password_required? }, :confirmation => true
+      #   validates :password, presence: true, confirmation: true, if: :password_required?
       #
+      # Finally, the options +:if+, +:unless+, +:on+, +:allow_blank+, +:allow_nil+
+      # and +:strict+ can be given to one specific validator, as a hash:
       #
+      #   validates :password, presence: { if: :password_required? }, confirmation: true
       def validates(*attributes)
         defaults = attributes.extract_options!.dup
         validations = defaults.slice!(*_validates_default_keys)
@@ -122,8 +122,20 @@ module ActiveModel
       # users and are considered exceptional. So each validator defined with bang
       # or <tt>:strict</tt> option set to <tt>true</tt> will always raise
       # <tt>ActiveModel::StrictValidationFailed</tt> instead of adding error
-      # when validation fails.
-      # See <tt>validates</tt> for more information about the validation itself.
+      # when validation fails. See <tt>validates</tt> for more information about
+      # the validation itself.
+      #
+      #   class Person
+      #     include ActiveModel::Validations
+      #
+      #     attr_accessor :name
+      #     validates! :name, presence: true
+      #   end
+      #
+      #   person = Person.new
+      #   person.name = ''
+      #   person.valid?
+      #   # => ActiveModel::StrictValidationFailed: Name can't be blank
       def validates!(*attributes)
         options = attributes.extract_options!
         options[:strict] = true
@@ -134,7 +146,7 @@ module ActiveModel
 
       # When creating custom validators, it might be useful to be able to specify
       # additional default keys. This can be done by overwriting this method.
-      def _validates_default_keys
+      def _validates_default_keys #:nodoc:
         [:if, :unless, :on, :allow_blank, :allow_nil , :strict]
       end
 
diff --git a/activemodel/lib/active_model/validations/with.rb b/activemodel/lib/active_model/validations/with.rb
index 3c516f8b22..869591cd9e 100644
--- a/activemodel/lib/active_model/validations/with.rb
+++ b/activemodel/lib/active_model/validations/with.rb
@@ -34,7 +34,7 @@ module ActiveModel
       #   class MyValidator < ActiveModel::Validator
       #     def validate(record)
       #       if some_complex_logic
-      #         record.errors.add :base, "This record is invalid"
+      #         record.errors.add :base, 'This record is invalid'
       #       end
       #     end
       #
@@ -48,30 +48,32 @@ module ActiveModel
       #
       #   class Person
       #     include ActiveModel::Validations
-      #     validates_with MyValidator, MyOtherValidator, :on => :create
+      #     validates_with MyValidator, MyOtherValidator, on: :create
       #   end
       #
       # Configuration options:
       # * <tt>:on</tt> - Specifies when this validation is active
-      #   (<tt>:create</tt> or <tt>:update</tt>
+      #   (<tt>:create</tt> or <tt>:update</tt>.
       # * <tt>:if</tt> - Specifies a method, proc or string to call to determine
-      #   if the validation should occur (e.g. <tt>:if => :allow_validation</tt>,
-      #   or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>).
-      #   The method, proc or string should return or evaluate to a true or false value.
+      #   if the validation should occur (e.g. <tt>if: :allow_validation</tt>,
+      #   or <tt>if: Proc.new { |user| user.signup_step > 2 }</tt>).
+      #   The method, proc or string should return or evaluate to a +true+ or
+      #   +false+ value.
       # * <tt>:unless</tt> - Specifies a method, proc or string to call to
       #   determine if the validation should not occur
-      #   (e.g. <tt>:unless => :skip_validation</tt>, or
-      #   <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>).
-      #   The method, proc or string should return or evaluate to a true or false value.
+      #   (e.g. <tt>unless: :skip_validation</tt>, or
+      #   <tt>unless: Proc.new { |user| user.signup_step <= 2 }</tt>).
+      #   The method, proc or string should return or evaluate to a +true+ or
+      #   +false+ value.
       # * <tt>:strict</tt> - Specifies whether validation should be strict.
       #   See <tt>ActiveModel::Validation#validates!</tt> for more information.
       #
       # If you pass any additional configuration options, they will be passed
-      # to the class and available as <tt>options</tt>:
+      # to the class and available as +options+:
       #
       #   class Person
       #     include ActiveModel::Validations
-      #     validates_with MyValidator, :my_custom_key => "my custom value"
+      #     validates_with MyValidator, my_custom_key: 'my custom value'
       #   end
       #
       #   class MyValidator < ActiveModel::Validator
@@ -119,17 +121,17 @@ module ActiveModel
     #   class Person
     #     include ActiveModel::Validations
     #
-    #     validate :instance_validations, :on => :create
+    #     validate :instance_validations, on: :create
     #
     #     def instance_validations
     #       validates_with MyValidator, MyOtherValidator
     #     end
     #   end
     #
-    # Standard configuration options (:on, :if and :unless), which are
-    # available on the class version of +validates_with+, should instead be
-    # placed on the +validates+ method as these are applied and tested
-    # in the callback.
+    # Standard configuration options (<tt>:on</tt>, <tt>:if</tt> and
+    # <tt>:unless</tt>), which are available on the class version of
+    # +validates_with+, should instead be placed on the +validates+ method
+    # as these are applied and tested in the callback.
     #
     # If you pass any additional configuration options, they will be passed
     # to the class and available as +options+, please refer to the