update AR::Validations::UniquenessValidator documentation [ci skip]

1 files changed, 45 insertions, 31 deletions

diff --git a/activerecord/lib/active_record/validations/uniqueness.rb b/activerecord/lib/active_record/validations/uniqueness.rb
index 5a24135f8e..c117872ac8 100644
--- a/activerecord/lib/active_record/validations/uniqueness.rb
+++ b/activerecord/lib/active_record/validations/uniqueness.rb
@@ -2,7 +2,7 @@ require 'active_support/core_ext/array/prepend_and_append'
 
 module ActiveRecord
   module Validations
-    class UniquenessValidator < ActiveModel::EachValidator
+    class UniquenessValidator < ActiveModel::EachValidator #:nodoc:
       def initialize(options)
         super(options.reverse_merge(:case_sensitive => true))
       end
@@ -87,54 +87,67 @@ module ActiveRecord
     end
 
     module ClassMethods
-      # Validates whether the value of the specified attributes are unique across the system.
-      # Useful for making sure that only one user
+      # Validates whether the value of the specified attributes are unique
+      # across the system. Useful for making sure that only one user
       # can be named "davidhh".
       #
       #   class Person < ActiveRecord::Base
       #     validates_uniqueness_of :user_name
       #   end
       #
-      # It can also validate whether the value of the specified attributes are unique based on a scope parameter:
+      # It can also validate whether the value of the specified attributes are
+      # unique based on a <tt>:scope</tt> parameter:
       #
       #   class Person < ActiveRecord::Base
-      #     validates_uniqueness_of :user_name, :scope => :account_id
+      #     validates_uniqueness_of :user_name, scope: :account_id
       #   end
       #
-      # Or even multiple scope parameters. For example, making sure that a teacher can only be on the schedule once
-      # per semester for a particular class.
+      # Or even multiple scope parameters. For example, making sure that a
+      # teacher can only be on the schedule once per semester for a particular
+      # class.
       #
       #   class TeacherSchedule < ActiveRecord::Base
-      #     validates_uniqueness_of :teacher_id, :scope => [:semester_id, :class_id]
+      #     validates_uniqueness_of :teacher_id, scope: [:semester_id, :class_id]
       #   end
       #
-      # It is also possible to limit the uniqueness constraint to a set of records matching certain conditions.
-      # In this example archived articles are not being taken into consideration when validating uniqueness
+      # It is also possible to limit the uniqueness constraint to a set of
+      # records matching certain conditions. In this example archived articles
+      # are not being taken into consideration when validating uniqueness
       # of the title attribute:
       #
       #   class Article < ActiveRecord::Base
-      #     validates_uniqueness_of :title, :conditions => where('status != ?', 'archived')
+      #     validates_uniqueness_of :title, conditions: where('status != ?', 'archived')
       #   end
       #
-      # When the record is created, a check is performed to make sure that no record exists in the database
-      # with the given value for the specified attribute (that maps to a column). When the record is updated,
+      # When the record is created, a check is performed to make sure that no
+      # record exists in the database with the given value for the specified
+      # attribute (that maps to a column). When the record is updated,
       # the same check is made but disregarding the record itself.
       #
       # Configuration options:
-      # * <tt>:message</tt> - Specifies a custom error message (default is: "has already been taken").
-      # * <tt>:scope</tt> - One or more columns by which to limit the scope of the uniqueness constraint.
-      # * <tt>:conditions</tt> - Specify the conditions to be included as a <tt>WHERE</tt> SQL fragment to limit
-      #   the uniqueness constraint lookup. (e.g. <tt>:conditions => where('status = ?', 'active')</tt>)
-      # * <tt>:case_sensitive</tt> - Looks for an exact match. Ignored by non-text columns (+true+ by default).
-      # * <tt>:allow_nil</tt> - If set to true, skips this validation if the attribute is +nil+ (default is +false+).
-      # * <tt>:allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is +false+).
-      # * <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.
-      # * <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.
+      #
+      # * <tt>:message</tt> - Specifies a custom error message (default is:
+      #   "has already been taken").
+      # * <tt>:scope</tt> - One or more columns by which to limit the scope of
+      #   the uniqueness constraint.
+      # * <tt>:conditions</tt> - Specify the conditions to be included as a
+      #   <tt>WHERE</tt> SQL fragment to limit the uniqueness constraint lookup
+      #   (e.g. <tt>conditions: where('status = ?', 'active')</tt>).
+      # * <tt>:case_sensitive</tt> - Looks for an exact match. Ignored by
+      #   non-text columns (+true+ by default).
+      # * <tt>:allow_nil</tt> - If set to +true+, skips this validation if the
+      #   attribute is +nil+ (default is +false+).
+      # * <tt>:allow_blank</tt> - If set to +true+, skips this validation if the
+      #   attribute is blank (default is +false+).
+      # * <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.
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to
+      #   determine if the validation should ot 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.
       #
       # === Concurrency and integrity
       #
@@ -190,15 +203,16 @@ module ActiveRecord
       #
       # The bundled ActiveRecord::ConnectionAdapters distinguish unique index
       # constraint errors from other types of database errors by throwing an
-      # ActiveRecord::RecordNotUnique exception.
-      # For other adapters you will have to parse the (database-specific) exception
-      # message to detect such a case.
+      # ActiveRecord::RecordNotUnique exception. For other adapters you will
+      # have to parse the (database-specific) exception message to detect such
+      # a case.
+      #
       # The following bundled adapters throw the ActiveRecord::RecordNotUnique exception:
+      #
       # * ActiveRecord::ConnectionAdapters::MysqlAdapter
       # * ActiveRecord::ConnectionAdapters::Mysql2Adapter
       # * ActiveRecord::ConnectionAdapters::SQLite3Adapter
       # * ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
-      #
       def validates_uniqueness_of(*attr_names)
         validates_with UniquenessValidator, _merge_attributes(attr_names)
       end