update #validates and #validates! documentation [ci skip]

1 files changed, 43 insertions, 31 deletions

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