minimal docs for transactions

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

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|

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