Add more information about transactions.

1 files changed, 16 insertions, 2 deletions

diff --git a/activerecord/lib/active_record/transactions.rb b/activerecord/lib/active_record/transactions.rb
index 75b2460cf7..b9def51363 100644
--- a/activerecord/lib/active_record/transactions.rb
+++ b/activerecord/lib/active_record/transactions.rb
@@ -25,7 +25,7 @@ module ActiveRecord
     # have a number of statements that must be executed together or not at all.
     # Example:
     #
-    #   transaction do
+    #   ActiveRecord::Base.transaction do
     #     david.withdrawal(100)
     #     mary.deposit(100)
     #   end
@@ -40,7 +40,9 @@ module ActiveRecord
     #
     # Though the transaction class method is called on some Active Record class,
     # the objects within the transaction block need not all be instances of
-    # that class.
+    # that class. This is because transactions are per-database connection, not
+    # per-model.
+    #
     # In this example a <tt>Balance</tt> record is transactionally saved even
     # though <tt>transaction</tt> is called on the <tt>Account</tt> class:
     #
@@ -49,6 +51,14 @@ module ActiveRecord
     #     account.save!
     #   end
     #
+    # Note that the +transaction+ method is also available as a model instance
+    # method. For example, you can also do this:
+    #
+    #   balance.transaction do
+    #     balance.save!
+    #     account.save!
+    #   end
+    #
     # == Transactions are not distributed across database connections
     #
     # A transaction acts on a single database connection.  If you have
@@ -95,6 +105,7 @@ module ActiveRecord
       end
     end
 
+    # See ActiveRecord::Transactions::ClassMethods for detailed documentation.
     def transaction(&block)
       self.class.transaction(&block)
     end
@@ -131,6 +142,9 @@ module ActiveRecord
     # Executes +method+ within a transaction and captures its return value as a
     # status flag. If the status is true the transaction is committed, otherwise
     # a ROLLBACK is issued. In any case the status flag is returned.
+    #
+    # This method is available within the context of an ActiveRecord::Base
+    # instance.
     def with_transaction_returning_status(method, *args)
       status = nil
       transaction do