Provide brief introduction to what optimistic locking is. Closes #8097. [fearoffish]

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

1 files changed, 10 insertions, 0 deletions

diff --git a/activerecord/lib/active_record/locking/optimistic.rb b/activerecord/lib/active_record/locking/optimistic.rb
index 7b7f87341e..23e7239d5e 100644
--- a/activerecord/lib/active_record/locking/optimistic.rb
+++ b/activerecord/lib/active_record/locking/optimistic.rb
@@ -1,5 +1,15 @@
 module ActiveRecord
   module Locking
+    # == What is Optimistic Locking
+    #
+    # Optimistic locking allows multiple users to access the same record for edits, and assumes a minimum of 
+    # conflicts with the data.  It does this by checking whether another process has made changes to a record since
+    # it was opened, an ActiveRecord::StaleObjectError is thrown if that has occurred and the update is ignored.
+    #
+    # Check out ActiveRecord::Locking::Pessimistic for an alternative.
+    #
+    # == Usage
+    #
     # Active Records support optimistic locking if the field <tt>lock_version</tt> is present.  Each update to the
     # record increments the lock_version column and the locking facilities ensure that records instantiated twice
     # will let the last one saved raise a StaleObjectError if the first was also updated. Example: