Add documentation about the virtual attribute added by...

Add documentation about the virtual attribute added by validates_confirmation_of and its behavior. Closes #8815 [JEG2, matt, kampers]

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

activerecord/CHANGELOG

 *SVN*
 
+* Add documentation about the virtual attribute added by validates_confirmation_of and its behavior. Closes #8815 [JEG2, matt, kampers]
+
 * Add documentation for freeze and readonly related methods. Closes #8878 [pelargir, jeremymcanally]
 
 * Document the timestamps schema definition method. Closes #9000 [mikong]

activerecord/lib/active_record/validations.rb

@@ -383,9 +383,12 @@ def validates_each(*attrs)
       #     <%= password_field "person", "password" %>
       #     <%= password_field "person", "password_confirmation" %>
       #
-      # The person has to already have a password attribute (a column in the people table), but the password_confirmation is virtual.
-      # It exists only as an in-memory variable for validating the password. This check is performed only if password_confirmation
-      # is not nil and by default on save.
+      # The added +password_confirmation+ attribute is virtual; it exists only as an in-memory attribute for validating the password.
+      # To achieve this, the validation adds acccessors to the model for the confirmation attribute. NOTE: This check is performed
+      # only if +password_confirmation+ is not nil, and by default only on save. To require confirmation, make sure to add a presence
+      # check for the confirmation attribute:
+      #
+      #   validates_presence_of :password_confirmation, :if => :password_changed?
       #
       # Configuration options:
       # * <tt>message</tt> - A custom error message (default is: "doesn't match confirmation")