Some more info about the effect of calling the clear method upon a model's errors collection (AR Validations an Callbacks Guide)

2 files changed, 14 insertions, 8 deletions

diff --git a/railties/doc/guides/html/activerecord_validations_callbacks.html b/railties/doc/guides/html/activerecord_validations_callbacks.html
index 75c0f26a45..27f6c51d4f 100644
--- a/railties/doc/guides/html/activerecord_validations_callbacks.html
+++ b/railties/doc/guides/html/activerecord_validations_callbacks.html
@@ -405,7 +405,7 @@ http://www.gnu.org/software/src-highlite -->
 >> p.new_record?

 =&gt; false</tt></pre>

 </div></div>

-<div class="para"><p>Saving new records means sending an SQL insert operation to the database, while saving existing records (by calling either <tt>save</tt> or <tt>update_attributes</tt>) will result in a SQL update operation. Active Record will use this facts to perform validations upon your objects, avoiding then to be recorded to the database if their inner state is invalid in some way. You can specify validations that will be beformed every time a object is saved, just when you're creating a new record or when you're updating an existing one.</p></div>

+<div class="para"><p>Saving new records means sending an SQL insert operation to the database, while saving existing records (by calling either <tt>save</tt> or <tt>update_attributes</tt>) will result in a SQL update operation. Active Record will use these facts to perform validations upon your objects, avoiding then to be recorded to the database if their inner state is invalid in some way. You can specify validations that will be beformed every time a object is saved, just when you're creating a new record or when you're updating an existing one.</p></div>

 <div class="admonitionblock">

 <table><tr>

 <td class="icon">

@@ -899,7 +899,7 @@ person<span style="color: #990000">.</span>errors<span style="color: #990000">.<
 <div class="ilist"><ul>

 <li>

 <p>

-<tt>clear</tt> is used when you intentionally wants to clear all the messages in the <tt>errors</tt> collection.

+<tt>clear</tt> is used when you intentionally want to clear all the messages in the <tt>errors</tt> collection. However, calling <tt>errors.clear</tt> upon an invalid object won't make it valid: the <tt>errors</tt> collection will now be empty, but the next time you call <tt>valid?</tt> or any method that tries to save this object to the database, the validations will run. If any of them fails, the <tt>errors</tt> collection will get filled again.

 </p>

 </li>

 </ul></div>

@@ -914,12 +914,15 @@ http://www.gnu.org/software/src-highlite -->
 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

 

 person <span style="color: #990000">=</span> Person<span style="color: #990000">.</span>new

-puts person<span style="color: #990000">.</span>valid? <span style="font-style: italic"><span style="color: #9A1900"># =&gt; false</span></span>

+person<span style="color: #990000">.</span>valid? <span style="font-style: italic"><span style="color: #9A1900"># =&gt; false</span></span>

 person<span style="color: #990000">.</span>errors<span style="color: #990000">.</span>on<span style="color: #990000">(:</span>name<span style="color: #990000">)</span>

 <span style="font-style: italic"><span style="color: #9A1900"># =&gt; ["can't be blank", "is too short (minimum is 3 characters)"]</span></span>

 

 person<span style="color: #990000">.</span>errors<span style="color: #990000">.</span>clear

-person<span style="color: #990000">.</span>errors <span style="font-style: italic"><span style="color: #9A1900"># =&gt; nil</span></span>

+person<span style="color: #990000">.</span>errors<span style="color: #990000">.</span>empty? <span style="font-style: italic"><span style="color: #9A1900"># =&gt; true</span></span>

+p<span style="color: #990000">.</span>save <span style="font-style: italic"><span style="color: #9A1900"># =&gt; false</span></span>

+p<span style="color: #990000">.</span>errors<span style="color: #990000">.</span>on<span style="color: #990000">(:</span>name<span style="color: #990000">)</span>

+<span style="font-style: italic"><span style="color: #9A1900"># =&gt; ["can't be blank", "is too short (minimum is 3 characters)"]</span></span>

 </tt></pre></div></div>

 </div>

 <h2 id="_callbacks">8. Callbacks</h2>

diff --git a/railties/doc/guides/source/activerecord_validations_callbacks.txt b/railties/doc/guides/source/activerecord_validations_callbacks.txt
index 86a758e122..7e9532911c 100644
--- a/railties/doc/guides/source/activerecord_validations_callbacks.txt
+++ b/railties/doc/guides/source/activerecord_validations_callbacks.txt
@@ -47,7 +47,7 @@ We can see how it works by looking at the following script/console output:
 => false
 ------------------------------------------------------------------
 
-Saving new records means sending an SQL insert operation to the database, while saving existing records (by calling either +save+ or +update_attributes+) will result in a SQL update operation. Active Record will use this facts to perform validations upon your objects, avoiding then to be recorded to the database if their inner state is invalid in some way. You can specify validations that will be beformed every time a object is saved, just when you're creating a new record or when you're updating an existing one.
+Saving new records means sending an SQL insert operation to the database, while saving existing records (by calling either +save+ or +update_attributes+) will result in a SQL update operation. Active Record will use these facts to perform validations upon your objects, avoiding then to be recorded to the database if their inner state is invalid in some way. You can specify validations that will be beformed every time a object is saved, just when you're creating a new record or when you're updating an existing one.
 
 CAUTION: There are four methods that when called will trigger validation: +save+, +save!+, +update_attributes+ and +update_attributes!+. There is one method left, which is +update_attribute+. This method will update the value of an attribute without triggering any validation, so be careful when using +update_attribute+, since it can let you save your objects in an invalid state.
 
@@ -477,7 +477,7 @@ person.errors.on(:name)
 # => ["can't be blank", "is too short (minimum is 3 characters)"]
 ------------------------------------------------------------------
 
-* +clear+ is used when you intentionally wants to clear all the messages in the +errors+ collection.
+* +clear+ is used when you intentionally want to clear all the messages in the +errors+ collection. However, calling +errors.clear+ upon an invalid object won't make it valid: the +errors+ collection will now be empty, but the next time you call +valid?+ or any method that tries to save this object to the database, the validations will run. If any of them fails, the +errors+ collection will get filled again.
 
 [source, ruby]
 ------------------------------------------------------------------
@@ -487,12 +487,15 @@ class Person < ActiveRecord::Base
 end
 
 person = Person.new
-puts person.valid? # => false
+person.valid? # => false
 person.errors.on(:name) 
 # => ["can't be blank", "is too short (minimum is 3 characters)"]
 
 person.errors.clear
-person.errors # => nil
+person.errors.empty? # => true  
+p.save # => false
+p.errors.on(:name)
+# => ["can't be blank", "is too short (minimum is 3 characters)"]
 ------------------------------------------------------------------
 
 == Callbacks