Add warning about the proper way to validate the presence of a foreign key. Closes #4147. [Francois Beausoleil <francois.beausoleil@gmail.com>]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@4285 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

1 files changed, 12 insertions, 0 deletions

diff --git a/activerecord/lib/active_record/validations.rb b/activerecord/lib/active_record/validations.rb
index 9e58599f81..d416773464 100755
--- a/activerecord/lib/active_record/validations.rb
+++ b/activerecord/lib/active_record/validations.rb
@@ -386,6 +386,18 @@ module ActiveRecord
       # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should
       # occur (e.g. :if => :allow_validation, or :if => Proc.new { |user| user.signup_step > 2 }).  The
       # method, proc or string should return or evaluate to a true or false value.
+      #
+      # === Warning
+      # Validate the presence of the foreign key, not the instance variable itself.
+      # Do this:
+      #  validate_presence_of :invoice_id
+      #
+      # Not this:
+      #  validate_presence_of :invoice
+      #
+      # If you validate the presence of the associated object, you will get
+      # failures on saves when both the parent object and the child object are
+      # new.
       def validates_presence_of(*attr_names)
         configuration = { :message => ActiveRecord::Errors.default_error_messages[:blank], :on => :save }
         configuration.update(attr_names.pop) if attr_names.last.is_a?(Hash)