lib/active_model/validator.rb in activemodel-3.0.20 vs lib/active_model/validator.rb in activemodel-3.1.0.beta1

@@ -1,8 +1,9 @@
 require 'active_support/core_ext/array/wrap'
 require "active_support/core_ext/module/anonymous"
 require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/object/inclusion'
 
 module ActiveModel #:nodoc:
 
   # == Active Model Validator
   #
@@ -61,31 +62,31 @@
   #       @my_custom_field = options[:field_name] || :first_name
   #     end
   #   end
   #
   # The easiest way to add custom validators for validating individual attributes
-  # is with the convenient ActiveModel::EachValidator for example:
+  # is with the convenient <tt>ActiveModel::EachValidator</tt>. For example:
   #
   #   class TitleValidator < ActiveModel::EachValidator
   #     def validate_each(record, attribute, value)
-  #       record.errors[attribute] << 'must be Mr. Mrs. or Dr.' unless ['Mr.', 'Mrs.', 'Dr.'].include?(value)
+  #       record.errors[attribute] << 'must be Mr. Mrs. or Dr.' unless value.in?(['Mr.', 'Mrs.', 'Dr.'])
   #     end
   #   end
   #
   # This can now be used in combination with the +validates+ method
-  # (see ActiveModel::Validations::ClassMethods.validates for more on this)
+  # (see <tt>ActiveModel::Validations::ClassMethods.validates</tt> for more on this)
   #
   #   class Person
   #     include ActiveModel::Validations
   #     attr_accessor :title
   #
-  #     validates :title, :presence => true, :title => true
+  #     validates :title, :presence => true
   #   end
   #
   # Validator may also define a +setup+ instance method which will get called
-  # with the class that using that validator as it's argument. This can be
-  # useful when there are prerequisites such as an attr_accessor being present
+  # with the class that using that validator as its argument. This can be
+  # useful when there are prerequisites such as an +attr_accessor+ being present
   # for example:
   #
   #   class MyValidator < ActiveModel::Validator
   #     def setup(klass)
   #       klass.send :attr_accessor, :custom_attribute
@@ -96,14 +97,12 @@
   # class level <tt>validates_with</tt> method.
   #
   class Validator
     attr_reader :options
 
-    # Returns the kind of the validator.
+    # Returns the kind of the validator. Examples:
     #
-    # == Examples
-    #
     #   PresenceValidator.kind   # => :presence
     #   UniquenessValidator.kind # => :uniqueness
     #
     def self.kind
       @kind ||= name.split('::').last.underscore.sub(/_validator$/, '').to_sym unless anonymous?
@@ -120,19 +119,19 @@
     end
 
     # Override this method in subclasses with validation logic, adding errors
     # to the records +errors+ array where necessary.
     def validate(record)
-      raise NotImplementedError
+      raise NotImplementedError, "Subclasses must implement a validate(record) method."
     end
   end
 
-  # EachValidator is a validator which iterates through the attributes given
-  # in the options hash invoking the validate_each method passing in the
+  # +EachValidator+ is a validator which iterates through the attributes given
+  # in the options hash invoking the <tt>validate_each</tt> method passing in the
   # record, attribute and value.
   #
-  # All Active Model validations are built on top of this Validator.
+  # All Active Model validations are built on top of this validator.
   class EachValidator < Validator
     attr_reader :attributes
 
     # Returns a new validator instance. All options will be available via the
     # +options+ reader, however the <tt>:attributes</tt> option will be removed
@@ -156,22 +155,21 @@
     end
 
     # Override this method in subclasses with the validation logic, adding
     # errors to the records +errors+ array where necessary.
     def validate_each(record, attribute, value)
-      raise NotImplementedError
+      raise NotImplementedError, "Subclasses must implement a validate_each(record, attribute, value) method"
     end
 
     # Hook method that gets called by the initializer allowing verification
     # that the arguments supplied are valid. You could for example raise an
-    # ArgumentError when invalid options are supplied.
+    # +ArgumentError+ when invalid options are supplied.
     def check_validity!
     end
   end
 
-  # BlockValidator is a special EachValidator which receives a block on initialization
-  # and call this block for each attribute being validated. +validates_each+ uses this
-  # Validator.
+  # +BlockValidator+ is a special +EachValidator+ which receives a block on initialization
+  # and call this block for each attribute being validated. +validates_each+ uses this validator.
   class BlockValidator < EachValidator
     def initialize(options, &block)
       @block = block
       super
     end