activerecord 3.0.0 → 4.0.0

data/lib/active_record/test_case.rb

@@ -1,8 +1,15 @@
+require 'active_support/test_case'
+
+ActiveSupport::Deprecation.warn('ActiveRecord::TestCase is deprecated, please use ActiveSupport::TestCase')
 module ActiveRecord
   # = Active Record Test Case
   #
   # Defines some test assertions to test against SQL queries.
   class TestCase < ActiveSupport::TestCase #:nodoc:
+    def teardown
+      SQLCounter.clear_log
+    end
+
     def assert_date_from_db(expected, actual, message = nil)
       # SybaseAdapter doesn't have a separate column type just for dates,
       # so the time is in the string and incorrectly formatted
@@ -14,54 +21,76 @@ module ActiveRecord
     end
 
     def assert_sql(*patterns_to_match)
-      $queries_executed = []
+      SQLCounter.clear_log
       yield
+      SQLCounter.log_all
     ensure
       failed_patterns = []
       patterns_to_match.each do |pattern|
-        failed_patterns << pattern unless $queries_executed.any?{ |sql| pattern === sql }
+        failed_patterns << pattern unless SQLCounter.log_all.any?{ |sql| pattern === sql }
       end
-      assert failed_patterns.empty?, "Query pattern(s) #{failed_patterns.map{ |p| p.inspect }.join(', ')} not found.#{$queries_executed.size == 0 ? '' : "\nQueries:\n#{$queries_executed.join("\n")}"}"
+      assert failed_patterns.empty?, "Query pattern(s) #{failed_patterns.map{ |p| p.inspect }.join(', ')} not found.#{SQLCounter.log.size == 0 ? '' : "\nQueries:\n#{SQLCounter.log.join("\n")}"}"
     end
 
-    def assert_queries(num = 1)
-      $queries_executed = []
+    def assert_queries(num = 1, options = {})
+      ignore_none = options.fetch(:ignore_none) { num == :any }
+      SQLCounter.clear_log
       yield
     ensure
-      %w{ BEGIN COMMIT }.each { |x| $queries_executed.delete(x) }
-      assert_equal num, $queries_executed.size, "#{$queries_executed.size} instead of #{num} queries were executed.#{$queries_executed.size == 0 ? '' : "\nQueries:\n#{$queries_executed.join("\n")}"}"
+      the_log = ignore_none ? SQLCounter.log_all : SQLCounter.log
+      if num == :any
+        assert_operator the_log.size, :>=, 1, "1 or more queries expected, but none were executed."
+      else
+        mesg = "#{the_log.size} instead of #{num} queries were executed.#{the_log.size == 0 ? '' : "\nQueries:\n#{the_log.join("\n")}"}"
+        assert_equal num, the_log.size, mesg
+      end
     end
 
     def assert_no_queries(&block)
-      assert_queries(0, &block)
+      assert_queries(0, :ignore_none => true, &block)
     end
 
-    def self.use_concurrent_connections
-      setup :connection_allow_concurrency_setup
-      teardown :connection_allow_concurrency_teardown
+  end
+
+  class SQLCounter
+    class << self
+      attr_accessor :ignored_sql, :log, :log_all
+      def clear_log; self.log = []; self.log_all = []; end
     end
 
-    def connection_allow_concurrency_setup
-      @connection = ActiveRecord::Base.remove_connection
-      ActiveRecord::Base.establish_connection(@connection.merge({:allow_concurrency => true}))
+    self.clear_log
+
+    self.ignored_sql = [/^PRAGMA/, /^SELECT currval/, /^SELECT CAST/, /^SELECT @@IDENTITY/, /^SELECT @@ROWCOUNT/, /^SAVEPOINT/, /^ROLLBACK TO SAVEPOINT/, /^RELEASE SAVEPOINT/, /^SHOW max_identifier_length/, /^BEGIN/, /^COMMIT/]
+
+    # FIXME: this needs to be refactored so specific database can add their own
+    # ignored SQL, or better yet, use a different notification for the queries
+    # instead examining the SQL content.
+    oracle_ignored     = [/^select .*nextval/i, /^SAVEPOINT/, /^ROLLBACK TO/, /^\s*select .* from all_triggers/im]
+    mysql_ignored      = [/^SHOW TABLES/i, /^SHOW FULL FIELDS/]
+    postgresql_ignored = [/^\s*select\b.*\bfrom\b.*pg_namespace\b/im, /^\s*select\b.*\battname\b.*\bfrom\b.*\bpg_attribute\b/im, /^SHOW search_path/i]
+    sqlite3_ignored =    [/^\s*SELECT name\b.*\bFROM sqlite_master/im]
+
+    [oracle_ignored, mysql_ignored, postgresql_ignored, sqlite3_ignored].each do |db_ignored_sql|
+      ignored_sql.concat db_ignored_sql
     end
 
-    def connection_allow_concurrency_teardown
-      ActiveRecord::Base.clear_all_connections!
-      ActiveRecord::Base.establish_connection(@connection)
+    attr_reader :ignore
+
+    def initialize(ignore = Regexp.union(self.class.ignored_sql))
+      @ignore = ignore
     end
 
-    def with_kcode(kcode)
-      if RUBY_VERSION < '1.9'
-        orig_kcode, $KCODE = $KCODE, kcode
-        begin
-          yield
-        ensure
-          $KCODE = orig_kcode
-        end
-      else
-        yield
-      end
+    def call(name, start, finish, message_id, values)
+      sql = values[:sql]
+
+      # FIXME: this seems bad. we should probably have a better way to indicate
+      # the query was cached
+      return if 'CACHE' == values[:name]
+
+      self.class.log_all << sql
+      self.class.log << sql unless ignore =~ sql
     end
   end
+
+  ActiveSupport::Notifications.subscribe('sql.active_record', SQLCounter.new)
 end

data/lib/active_record/timestamp.rb

@@ -1,3 +1,4 @@
+
 module ActiveRecord
   # = Active Record Timestamp
   #
@@ -7,47 +8,56 @@ module ActiveRecord
   #
   # Timestamping can be turned off by setting:
   #
-  #   <tt>ActiveRecord::Base.record_timestamps = false</tt>
+  #   config.active_record.record_timestamps = false
   #
   # Timestamps are in the local timezone by default but you can use UTC by setting:
   #
-  #   <tt>ActiveRecord::Base.default_timezone = :utc</tt>
+  #   config.active_record.default_timezone = :utc
   #
   # == Time Zone aware attributes
   #
   # By default, ActiveRecord::Base keeps all the datetime columns time zone aware by executing following code.
   #
-  #   ActiveRecord::Base.time_zone_aware_attributes = true
+  #   config.active_record.time_zone_aware_attributes = true
   #
   # This feature can easily be turned off by assigning value <tt>false</tt> .
   #
-  # If your attributes are time zone aware and you desire to skip time zone conversion for certain
-  # attributes then you can do following:
+  # If your attributes are time zone aware and you desire to skip time zone conversion to the current Time.zone
+  # when reading certain attributes then you can do following:
   #
-  #   Topic.skip_time_zone_conversion_for_attributes = [:written_on]
+  #   class Topic < ActiveRecord::Base
+  #     self.skip_time_zone_conversion_for_attributes = [:written_on]
+  #   end
   module Timestamp
     extend ActiveSupport::Concern
 
     included do
-      class_inheritable_accessor :record_timestamps, :instance_writer => false
+      class_attribute :record_timestamps
       self.record_timestamps = true
     end
 
+    def initialize_dup(other) # :nodoc:
+      clear_timestamp_attributes
+      super
+    end
+
   private
 
-    def create #:nodoc:
-      if record_timestamps
+    def create_record
+      if self.record_timestamps
         current_time = current_time_from_proper_timezone
 
         all_timestamp_attributes.each do |column|
-          write_attribute(column.to_s, current_time) if respond_to?(column) && self.send(column).nil?
+          if respond_to?(column) && respond_to?("#{column}=") && self.send(column).nil?
+            write_attribute(column.to_s, current_time)
+          end
         end
       end
 
       super
     end
 
-    def update(*args) #:nodoc:
+    def update_record(*args)
       if should_record_timestamps?
         current_time = current_time_from_proper_timezone
 
@@ -61,28 +71,49 @@ module ActiveRecord
     end
 
     def should_record_timestamps?
-      record_timestamps && (!partial_updates? || changed?)
+      self.record_timestamps && (!partial_writes? || changed? || (attributes.keys & self.class.serialized_attributes.keys).present?)
+    end
+
+    def timestamp_attributes_for_create_in_model
+      timestamp_attributes_for_create.select { |c| self.class.column_names.include?(c.to_s) }
     end
 
     def timestamp_attributes_for_update_in_model
-      timestamp_attributes_for_update.select { |c| respond_to?(c) }
+      timestamp_attributes_for_update.select { |c| self.class.column_names.include?(c.to_s) }
+    end
+
+    def all_timestamp_attributes_in_model
+      timestamp_attributes_for_create_in_model + timestamp_attributes_for_update_in_model
     end
 
-    def timestamp_attributes_for_update #:nodoc:
+    def timestamp_attributes_for_update
       [:updated_at, :updated_on]
     end
 
-    def timestamp_attributes_for_create #:nodoc:
+    def timestamp_attributes_for_create
       [:created_at, :created_on]
     end
 
-    def all_timestamp_attributes #:nodoc:
+    def all_timestamp_attributes
       timestamp_attributes_for_create + timestamp_attributes_for_update
     end
 
-    def current_time_from_proper_timezone #:nodoc:
+    def max_updated_column_timestamp
+      if (timestamps = timestamp_attributes_for_update.map { |attr| self[attr] }.compact).present?
+        timestamps.map { |ts| ts.to_time }.max
+      end
+    end
+
+    def current_time_from_proper_timezone
       self.class.default_timezone == :utc ? Time.now.utc : Time.now
     end
+
+    # Clear attributes and changed_attributes
+    def clear_timestamp_attributes
+      all_timestamp_attributes_in_model.each do |attribute_name|
+        self[attribute_name] = nil
+        changed_attributes.delete(attribute_name)
+      end
+    end
   end
 end
-

data/lib/active_record/transactions.rb

@@ -4,6 +4,7 @@ module ActiveRecord
   # See ActiveRecord::Transactions::ClassMethods for documentation.
   module Transactions
     extend ActiveSupport::Concern
+    ACTIONS = [:create, :destroy, :update]
 
     class TransactionError < ActiveRecordError # :nodoc:
     end
@@ -11,6 +12,7 @@ module ActiveRecord
     included do
       define_callbacks :commit, :rollback, :terminator => "result == false", :scope => [:kind, :name]
     end
+
     # = Active Record Transactions
     #
     # Transactions are protective blocks where SQL statements are only permanent
@@ -107,10 +109,10 @@ module ActiveRecord
     #
     #   # Suppose that we have a Number model with a unique column called 'i'.
     #   Number.transaction do
-    #     Number.create(:i => 0)
+    #     Number.create(i: 0)
     #     begin
     #       # This will raise a unique constraint error...
-    #       Number.create(:i => 0)
+    #       Number.create(i: 0)
     #     rescue ActiveRecord::StatementInvalid
     #       # ...which we ignore.
     #     end
@@ -118,7 +120,7 @@ module ActiveRecord
     #     # On PostgreSQL, the transaction is now unusable. The following
     #     # statement will cause a PostgreSQL error, even though the unique
     #     # constraint is no longer violated:
-    #     Number.create(:i => 1)
+    #     Number.create(i: 1)
     #     # => "PGError: ERROR:  current transaction is aborted, commands
     #     #     ignored until end of transaction block"
     #   end
@@ -130,38 +132,41 @@ module ActiveRecord
     #
     # +transaction+ calls can be nested. By default, this makes all database
     # statements in the nested transaction block become part of the parent
-    # transaction. For example:
+    # transaction. For example, the following behavior may be surprising:
     #
     #   User.transaction do
-    #     User.create(:username => 'Kotori')
+    #     User.create(username: 'Kotori')
     #     User.transaction do
-    #       User.create(:username => 'Nemu')
+    #       User.create(username: 'Nemu')
     #       raise ActiveRecord::Rollback
     #     end
     #   end
     #
-    #   User.find(:all)  # => empty
+    # creates both "Kotori" and "Nemu". Reason is the <tt>ActiveRecord::Rollback</tt>
+    # exception in the nested block does not issue a ROLLBACK. Since these exceptions
+    # are captured in transaction blocks, the parent block does not see it and the
+    # real transaction is committed.
     #
-    # It is also possible to requires a sub-transaction by passing
-    # <tt>:requires_new => true</tt>. If anything goes wrong, the
-    # database rolls back to the beginning of the sub-transaction
-    # without rolling back the parent transaction. For example:
+    # In order to get a ROLLBACK for the nested transaction you may ask for a real
+    # sub-transaction by passing <tt>requires_new: true</tt>. If anything goes wrong,
+    # the database rolls back to the beginning of the sub-transaction without rolling
+    # back the parent transaction. If we add it to the previous example:
     #
     #   User.transaction do
-    #     User.create(:username => 'Kotori')
-    #     User.transaction(:requires_new => true) do
-    #       User.create(:username => 'Nemu')
+    #     User.create(username: 'Kotori')
+    #     User.transaction(requires_new: true) do
+    #       User.create(username: 'Nemu')
     #       raise ActiveRecord::Rollback
     #     end
     #   end
     #
-    #   User.find(:all)  # => Returns only Kotori
+    # only "Kotori" is created. This works on MySQL and PostgreSQL. SQLite3 version >= '3.6.8' also supports it.
     #
     # Most databases don't support true nested transactions. At the time of
     # writing, the only database that we're aware of that supports true nested
     # transactions, is MS-SQL. Because of this, Active Record emulates nested
-    # transactions by using savepoints. See
-    # http://dev.mysql.com/doc/refman/5.0/en/savepoints.html
+    # transactions by using savepoints on MySQL and PostgreSQL. See
+    # http://dev.mysql.com/doc/refman/5.6/en/savepoint.html
     # for more information about savepoints.
     #
     # === Callbacks
@@ -190,7 +195,7 @@ module ActiveRecord
     # automatically released. The following example demonstrates the problem:
     #
     #   Model.connection.transaction do                           # BEGIN
-    #     Model.connection.transaction(:requires_new => true) do  # CREATE SAVEPOINT active_record_1
+    #     Model.connection.transaction(requires_new: true) do  # CREATE SAVEPOINT active_record_1
     #       Model.connection.create_table(...)                    # active_record_1 now automatically released
     #     end                                                     # RELEASE savepoint active_record_1
     #                                                             # ^^^^ BOOM! database error!
@@ -204,28 +209,56 @@ module ActiveRecord
         connection.transaction(options, &block)
       end
 
+      # This callback is called after a record has been created, updated, or destroyed.
+      #
+      # You can specify that the callback should only be fired by a certain action with
+      # the +:on+ option:
+      #
+      #   after_commit :do_foo, on: :create
+      #   after_commit :do_bar, on: :update
+      #   after_commit :do_baz, on: :destroy
+      #
+      #   after_commit :do_foo_bar, :on [:create, :update]
+      #   after_commit :do_bar_baz, :on [:update, :destroy]
+      #
+      # Note that transactional fixtures do not play well with this feature. Please
+      # use the +test_after_commit+ gem to have these hooks fired in tests.
       def after_commit(*args, &block)
-        options = args.last
-        if options.is_a?(Hash) && options[:on]
-          options[:if] = Array.wrap(options[:if])
-          options[:if] << "transaction_include_action?(:#{options[:on]})"
-        end
+        set_options_for_callbacks!(args)
         set_callback(:commit, :after, *args, &block)
       end
 
+      # This callback is called after a create, update, or destroy are rolled back.
+      #
+      # Please check the documentation of +after_commit+ for options.
       def after_rollback(*args, &block)
+        set_options_for_callbacks!(args)
+        set_callback(:rollback, :after, *args, &block)
+      end
+
+      private
+
+      def set_options_for_callbacks!(args)
         options = args.last
         if options.is_a?(Hash) && options[:on]
-          options[:if] = Array.wrap(options[:if])
-          options[:if] << "transaction_include_action?(:#{options[:on]})"
+          assert_valid_transaction_action(options[:on])
+          options[:if] = Array(options[:if])
+          fire_on = Array(options[:on]).map(&:to_sym)
+          options[:if] << "transaction_include_any_action?(#{fire_on})"
+        end
+      end
+
+      def assert_valid_transaction_action(actions)
+        actions = Array(actions)
+        if (actions - ACTIONS).any?
+          raise ArgumentError, ":on conditions for after_commit and after_rollback callbacks have to be one of #{ACTIONS.join(",")}"
         end
-        set_callback(:rollback, :after, *args, &block)
       end
     end
 
     # See ActiveRecord::Transactions::ClassMethods for detailed documentation.
-    def transaction(&block)
-      self.class.transaction(&block)
+    def transaction(options = {}, &block)
+      self.class.transaction(options, &block)
     end
 
     def destroy #:nodoc:
@@ -254,8 +287,11 @@ module ActiveRecord
     end
 
     # Call the after_commit callbacks
+    #
+    # Ensure that it is not called if the object was never persisted (failed create),
+    # but call it after the commit of a destroyed object
     def committed! #:nodoc:
-      _run_commit_callbacks
+      run_callbacks :commit if destroyed? || persisted?
     ensure
       clear_transaction_record_state
     end
@@ -263,7 +299,7 @@ module ActiveRecord
     # Call the after rollback callbacks. The restore_state argument indicates if the record
     # state should be rolled back to the beginning or just to the last savepoint.
     def rolledback!(force_restore_state = false) #:nodoc:
-      _run_rollback_callbacks
+      run_callbacks :rollback
     ensure
       restore_transaction_record_state(force_restore_state)
     end
@@ -286,7 +322,13 @@ module ActiveRecord
       status = nil
       self.class.transaction do
         add_to_transaction
-        status = yield
+        begin
+          status = yield
+        rescue ActiveRecord::Rollback
+          @_start_transaction_state[:level] = (@_start_transaction_state[:level] || 0) - 1
+          status = nil
+        end
+
         raise ActiveRecord::Rollback unless status
       end
       status
@@ -295,61 +337,62 @@ module ActiveRecord
     protected
 
     # Save the new record state and id of a record so it can be restored later if a transaction fails.
-    def remember_transaction_record_state #:nodoc
-      @_start_transaction_state ||= {}
+    def remember_transaction_record_state #:nodoc:
+      @_start_transaction_state[:id] = id if has_attribute?(self.class.primary_key)
       unless @_start_transaction_state.include?(:new_record)
-        @_start_transaction_state[:id] = id if has_attribute?(self.class.primary_key)
         @_start_transaction_state[:new_record] = @new_record
       end
       unless @_start_transaction_state.include?(:destroyed)
         @_start_transaction_state[:destroyed] = @destroyed
       end
       @_start_transaction_state[:level] = (@_start_transaction_state[:level] || 0) + 1
+      @_start_transaction_state[:frozen?] = @attributes.frozen?
     end
 
     # Clear the new record state and id of a record.
-    def clear_transaction_record_state #:nodoc
-      if defined?(@_start_transaction_state)
-        @_start_transaction_state[:level] = (@_start_transaction_state[:level] || 0) - 1
-        remove_instance_variable(:@_start_transaction_state) if @_start_transaction_state[:level] < 1
-      end
+    def clear_transaction_record_state #:nodoc:
+      @_start_transaction_state[:level] = (@_start_transaction_state[:level] || 0) - 1
+      @_start_transaction_state.clear if @_start_transaction_state[:level] < 1
     end
 
     # Restore the new record state and id of a record that was previously saved by a call to save_record_state.
-    def restore_transaction_record_state(force = false) #:nodoc
-      if defined?(@_start_transaction_state)
+    def restore_transaction_record_state(force = false) #:nodoc:
+      unless @_start_transaction_state.empty?
         @_start_transaction_state[:level] = (@_start_transaction_state[:level] || 0) - 1
-        if @_start_transaction_state[:level] < 1
-          restore_state = remove_instance_variable(:@_start_transaction_state)
-          if restore_state
-            @attributes = @attributes.dup if @attributes.frozen?
-            @new_record = restore_state[:new_record]
-            @destroyed = restore_state[:destroyed]
-            if restore_state[:id]
-              self.id = restore_state[:id]
-            else
-              @attributes.delete(self.class.primary_key)
-              @attributes_cache.delete(self.class.primary_key)
-            end
+        if @_start_transaction_state[:level] < 1 || force
+          restore_state = @_start_transaction_state
+          was_frozen = restore_state[:frozen?]
+          @attributes = @attributes.dup if @attributes.frozen?
+          @new_record = restore_state[:new_record]
+          @destroyed  = restore_state[:destroyed]
+          if restore_state.has_key?(:id)
+            self.id = restore_state[:id]
+          else
+            @attributes.delete(self.class.primary_key)
+            @attributes_cache.delete(self.class.primary_key)
           end
+          @attributes.freeze if was_frozen
+          @_start_transaction_state.clear
         end
       end
     end
 
     # Determine if a record was created or destroyed in a transaction. State should be one of :new_record or :destroyed.
-    def transaction_record_state(state) #:nodoc
-      @_start_transaction_state[state] if defined?(@_start_transaction_state)
+    def transaction_record_state(state) #:nodoc:
+      @_start_transaction_state[state]
     end
 
     # Determine if a transaction included an action for :create, :update, or :destroy. Used in filtering callbacks.
-    def transaction_include_action?(action) #:nodoc
-      case action
-      when :create
-        transaction_record_state(:new_record)
-      when :destroy
-        destroyed?
-      when :update
-        !(transaction_record_state(:new_record) || destroyed?)
+    def transaction_include_any_action?(actions) #:nodoc:
+      actions.any? do |action|
+        case action
+        when :create
+          transaction_record_state(:new_record)
+        when :destroy
+          destroyed?
+        when :update
+          !(transaction_record_state(:new_record) || destroyed?)
+        end
       end
     end
   end

data/lib/active_record/translation.rb

@@ -0,0 +1,22 @@
+module ActiveRecord
+  module Translation
+    include ActiveModel::Translation
+
+    # Set the lookup ancestors for ActiveModel.
+    def lookup_ancestors #:nodoc:
+      klass = self
+      classes = [klass]
+      return classes if klass == ActiveRecord::Base
+
+      while klass != klass.base_class
+        classes << klass = klass.superclass
+      end
+      classes
+    end
+
+    # Set the i18n scope to overwrite ActiveModel.
+    def i18n_scope #:nodoc:
+      :activerecord
+    end
+  end
+end

data/lib/active_record/validations/associated.rb

@@ -1,14 +1,16 @@
 module ActiveRecord
   module Validations
-    class AssociatedValidator < ActiveModel::EachValidator
+    class AssociatedValidator < ActiveModel::EachValidator #:nodoc:
       def validate_each(record, attribute, value)
-        return if (value.is_a?(Array) ? value : [value]).collect{ |r| r.nil? || r.valid? }.all?
-        record.errors.add(attribute, :invalid, options.merge(:value => value))
+        if Array.wrap(value).reject {|r| r.marked_for_destruction? || r.valid?}.any?
+          record.errors.add(attribute, :invalid, options.merge(:value => value))
+        end
       end
     end
 
     module ClassMethods
-      # Validates whether the associated object or objects are all valid themselves. Works with any kind of association.
+      # Validates whether the associated object or objects are all valid.
+      # Works with any kind of association.
       #
       #   class Book < ActiveRecord::Base
       #     has_many :pages
@@ -17,29 +19,28 @@ module ActiveRecord
       #     validates_associated :pages, :library
       #   end
       #
-      # Warning: If, after the above definition, you then wrote:
+      # WARNING: This validation must not be used on both ends of an association.
+      # Doing so will lead to a circular dependency and cause infinite recursion.
       #
-      #   class Page < ActiveRecord::Base
-      #     belongs_to :book
-      #
-      #     validates_associated :book
-      #   end
-      #
-      # this would specify a circular dependency and cause infinite recursion.
-      #
-      # NOTE: This validation will not fail if the association hasn't been assigned. If you want to
-      # ensure that the association is both present and guaranteed to be valid, you also need to
-      # use +validates_presence_of+.
+      # NOTE: This validation will not fail if the association hasn't been
+      # assigned. If you want to ensure that the association is both present and
+      # guaranteed to be valid, you also need to use +validates_presence_of+.
       #
       # Configuration options:
-      # * <tt>:message</tt> - A custom error message (default is: "is invalid")
-      # * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <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.
-      # * <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> - A custom error message (default is: "is invalid").
+      # * <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>.
+      # * <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.
       def validates_associated(*attr_names)
         validates_with AssociatedValidator, _merge_attributes(attr_names)
       end