Start blocking out some documentation.

- Fix some C rdoc so it is parsed correctly.
  - Fill out transaction testing.
  - Populate docs for DB options.

FossilOrigin-Name: f54dbfacf2dda100a116fdcc856ca5231e249f23238ca9d4355618e3a380a8f8

spec/mdbx/database_spec.rb

@@ -6,6 +6,12 @@ require_relative '../lib/helper'
 
 RSpec.describe( MDBX::Database ) do
 
+	after( :all ) do
+		db = described_class.open( TEST_DATABASE.to_s )
+		db.clear
+		db.close
+	end
+
 	it "disallows direct calls to #new" do
 		expect{ described_class.new }.
 			to raise_exception( NoMethodError, /private/ )
@@ -60,8 +66,6 @@ RSpec.describe( MDBX::Database ) do
 
 			db[ 'test' ] = nil
 			expect( db['test'] ).to be_nil
-
-			expect { db[ 'test' ] = nil }.to_not raise_exception
 		end
 
 		it "can return an array of its keys" do
@@ -84,9 +88,9 @@ RSpec.describe( MDBX::Database ) do
 		it "fail if the max_collections option is not specified when opening" do
 			db.close
 			db = described_class.open( TEST_DATABASE.to_s )
-			db.collection( 'bucket' )
-
-			expect{ db['key'] = true }.to raise_exception( /MDBX_DBS_FULL/ )
+			expect{
+				db.collection( 'bucket' )
+			} .to raise_exception( /not enabled/ )
 		end
 
 		it "disallows regular key/val storage for namespace keys" do
@@ -130,5 +134,94 @@ RSpec.describe( MDBX::Database ) do
 			expect( db['bucket'] ).to be_nil
 		end
 	end
+
+
+	context 'transactions' do
+
+		let!( :db ) { described_class.open( TEST_DATABASE.to_s, max_collections: 5 ) }
+
+		after( :each ) do
+			db.close
+		end
+
+		it "knows when a transaction is currently open" do
+			expect( db.in_transaction? ).to be_falsey
+			db.snapshot
+			expect( db.in_transaction? ).to be_truthy
+			db.abort
+			expect( db.in_transaction? ).to be_falsey
+
+			db.snapshot do
+				expect( db.in_transaction? ).to be_truthy
+			end
+			expect( db.in_transaction? ).to be_falsey
+		end
+
+		it "throws an error if changing collection mid-transaction" do
+			db.snapshot do
+				expect{ db.collection('nope') }.
+					to raise_exception( MDBX::DatabaseError, /transaction open/ )
+			end
+		end
+
+		it "are re-entrant" do
+			3.times { db.snapshot }
+			expect( db.in_transaction? ).to be_truthy
+		end
+
+		it "refuse to allow writes for read-only snapshots" do
+			db.snapshot
+			expect{ db[1] = true }.
+				to raise_exception( MDBX::DatabaseError, /permission denied/i )
+		end
+
+		it "revert changes via explicit rollbacks" do
+			db[ 1 ] = true
+			db.transaction
+			db[ 1 ] = false
+			expect( db[ 1 ] ).to be_falsey
+			db.rollback
+			expect( db[ 1 ] ).to be_truthy
+		end
+
+		it "revert changes via uncaught exceptions" do
+			db[ 1 ] = true
+			expect {
+				db.transaction do
+					db[ 1 ] = false
+					raise "boom"
+				end
+			}.to raise_exception( RuntimeError, "boom" )
+			expect( db[ 1 ] ).to be_truthy
+		end
+
+		it "revert changes via explicit exceptions" do
+			db[ 1 ] = true
+			expect {
+				db.transaction do
+					db[ 1 ] = false
+					raise MDBX::Rollback, "boom!"
+				end
+			}.to_not raise_exception
+			expect( db[ 1 ] ).to be_truthy
+		end
+
+		it "write changes after commit" do
+			db[ 1 ] = true
+			db.transaction
+			db[ 1 ] = false
+			expect( db[ 1 ] ).to be_falsey
+			db.commit
+			expect( db[ 1 ] ).to be_falsey
+		end
+
+		it "automatically write changes after block" do
+			db[ 1 ] = true
+			db.transaction do
+				db[ 1 ] = false
+			end
+			expect( db[ 1 ] ).to be_falsey
+		end
+	end
 end