rewrites AR's reload documentation

* It is no longer true that options are passed to find.

* Documents that ActiveRecord::RecordNotFound may be raised.

* Documents that the reload happens in-place.

* Documents that caches are wiped.

* Documents that the method returns self.

* Documents a couple of use cases.

1 files changed, 38 insertions, 4 deletions

diff --git a/activerecord/lib/active_record/persistence.rb b/activerecord/lib/active_record/persistence.rb
index a8905ed739..582006ea7d 100644
--- a/activerecord/lib/active_record/persistence.rb
+++ b/activerecord/lib/active_record/persistence.rb
@@ -333,10 +333,44 @@ module ActiveRecord
       toggle(attribute).update_attribute(attribute, self[attribute])
     end
 
-    # Reloads the attributes of this object from the database.
-    # The optional options argument is passed to find when reloading so you
-    # may do e.g. record.reload(lock: true) to reload the same record with
-    # an exclusive row lock.
+    # Reloads the record from the database.
+    #
+    # This method modifies the receiver in-place. Attributes are updated, and
+    # caches busted, in particular the associations cache.
+    #
+    # If the record no longer exists in the database <tt>ActiveRecord::RecordNotFound</tt>
+    # is raised. Otherwise, in addition to the in-place modification the method
+    # returns +self+ for convenience.
+    #
+    # The optional <tt>:lock</tt> flag option allows you to lock the reloaded record:
+    #
+    #   reload(lock: true) # reload with pessimistic locking
+    #
+    # Reloading is commonly used in test suites to test something is actually
+    # written to the database, or when some action modifies the corresponding
+    # row in the database but not the object in memory:
+    #
+    #   assert account.deposit!(25)
+    #   assert_equal 25, account.credit        # check it is updated in memory
+    #   assert_equal 25, account.reload.credit # check it is also persisted
+    #
+    # Another commom use case is optimistic locking handling:
+    #
+    #   def with_optimistic_retry
+    #     begin
+    #       yield
+    #     rescue ActiveRecord::StaleObjectError
+    #       begin
+    #         # Reload lock_version in particular.
+    #         reload
+    #       rescue ActiveRecord::RecordNotFound
+    #         # If the record is gone there is nothing to do.
+    #       else
+    #         retry
+    #       end
+    #     end
+    #   end
+    #
     def reload(options = nil)
       clear_aggregation_cache
       clear_association_cache