From d7ccecae9b4d1cb55b07e29ba5f0adf7399afd1d Mon Sep 17 00:00:00 2001
From: "Brian J. Cardiff" <bcardiff@manas.com.ar>
Date: Wed, 14 Dec 2016 12:13:46 -0300
Subject: [PATCH] minimal docs for transactions

---
 src/db/begin_transaction.cr |  9 +++++++++
 src/db/database.cr          |  2 ++
 src/db/transaction.cr       | 14 ++++++++++++++
 3 files changed, 25 insertions(+)

diff --git a/src/db/begin_transaction.cr b/src/db/begin_transaction.cr
index d985d70..a858afa 100644
--- a/src/db/begin_transaction.cr
+++ b/src/db/begin_transaction.cr
@@ -1,7 +1,16 @@
 module DB
   module BeginTransaction
+    # Creates a transaction from the current context.
+    # If is expected that either `Transaction#commit` or `Transaction#rollback`
+    # are called explictly to release the context.
     abstract def begin_transaction : Transaction
 
+    # yields a transaction from the current context.
+    # Query the database through `Transaction#connection` object.
+    # If an exception is thrown within the block a rollback is performed.
+    # The exception thrown is blubbled unless it is a `DB::Rollback`.
+    # From the yielded object `Transaction#commit` or `Transaction#rollback`
+    # can be called explicitly.
     def transaction
       tx = begin_transaction
       begin
diff --git a/src/db/database.cr b/src/db/database.cr
index 15b85c6..f69d5b3 100644
--- a/src/db/database.cr
+++ b/src/db/database.cr
@@ -105,6 +105,8 @@ module DB
       end
     end
 
+    # yields a `Transaction` from a connection of the pool
+    # Refer to `BeginTransaction#transaction` for documentation.
     def transaction
       using_connection do |cnn|
         cnn.transaction do |tx|
diff --git a/src/db/transaction.cr b/src/db/transaction.cr
index 6cf685b..46e45ce 100644
--- a/src/db/transaction.cr
+++ b/src/db/transaction.cr
@@ -1,14 +1,28 @@
 module DB
+  # Transactions should be started from `DB#transaction`, `Connection#transaction`
+  # or `Connection#begin_transaction`.
+  #
+  # Use `Transaction#connection` to submit statements to the database.
+  #
+  # Use `Transaction#commit` or `Transaction#rollback` to close the ongoing transaction
+  # explicitly. Or refer to `BeginTransaction#transaction` for documentation on how to
+  # use `#transaction(&block)` methods in `DB` and `Connection`.
+  #
+  # Nested transactions are supported by using sql `SAVEPOINT`. To start a nested
+  # transaction use `Transaction#transaction` or `Transaction#begin_transaction`.
+  #
   abstract class Transaction
     include Disposable
     include BeginTransaction
 
     abstract def connection : Connection
 
+    # commits the current transaction
     def commit
       close!
     end
 
+    # rollbacks the current transaction
     def rollback
       close!
     end