tests for transaction RAII behaviour, transaction documentation, minor doc fixes

src/transaction.cpp

@@ -1,17 +1,42 @@
 #include "transaction.h"
 
+/**
+ * \class LMDBAL::Transaction
+ * \brief Public read only transaction
+ *
+ * This class provides read only transactions you can use
+ * to speed to your queries keeping them thread safe.
+ * LMDBAL::Transaction is <b>NOT COPYABLE</b> but <b>MOVABLE</b>.
+ * Transaction can be in one of two states: active or terminated.
+ * The way to receive an active LMDBAL::Transaction is to call LMDBAL::Base::beginReadOnlyTransaction.
+ *
+ * Active transactions become terminated upon the call of LMDBAL::Transaction::terminate.
+ * Active transactions automaticaly terminate themselves upon destruction.
+ *
+ * You <b>CAN NOT</b> use inactive transactions for any query.
+ */
+
+/**
+ * \brief Constructs inactive transaction
+ */
 LMDBAL::Transaction::Transaction():
     txn(nullptr),
     active(false),
     parent(nullptr)
 {}
 
+/**
+ * \brief Constructs an active transaction
+ */
 LMDBAL::Transaction::Transaction(TransactionID txn, const Base* parent) :
     txn(txn),
     active(true),
     parent(parent)
 {}
 
+/**
+ * \brief Moves transaction to a new object
+ */
 LMDBAL::Transaction::Transaction(Transaction&& other):
     txn(other.txn),
     active(other.active),
@@ -20,10 +45,16 @@ LMDBAL::Transaction::Transaction(Transaction&& other):
     other.active = false;
 }
 
+/**
+ * \brief Destroys transaction
+ */
 LMDBAL::Transaction::~Transaction() {
     terminate();
 }
 
+/**
+ * \brief Move-assigns transaction to the new object
+ */
 LMDBAL::Transaction& LMDBAL::Transaction::operator=(Transaction&& other) {
     terminate();
 
@@ -36,6 +67,11 @@ LMDBAL::Transaction& LMDBAL::Transaction::operator=(Transaction&& other) {
     return *this;
 }
 
+/**
+ * \brief Terminates transaction if it was active
+ *
+ * Transaction becomes terminated after calling this method
+ */
 void LMDBAL::Transaction::terminate() {
     if (active) {
         parent->abortTransaction(txn);
@@ -43,26 +79,73 @@ void LMDBAL::Transaction::terminate() {
     }
 }
 
+/**
+ * \brief Returns transaction states
+ *
+ * \returns true if the transaction is active, false otherwise
+ */
 bool LMDBAL::Transaction::isActive() const {
     return active;      //todo may be it's better if I query it from DB?
 }
 
+
+/**
+ * \class LMDBAL::WriteTransaction
+ * \brief Public writable transaction
+ *
+ * This class provides writable transactions you can use
+ * to speed to your queries and modifications keeping them thread safe.
+ * LMDBAL::WriteTransaction is <b>NOT COPYABLE</b> but <b>MOVABLE</b>.
+ * Transaction can be in one of two states: active or terminated.
+ * The way to receive an active LMDBAL::WriteTransaction is to call LMDBAL::Base::beginTransaction.
+ * You can use LMDBAL::WriteTransaction for everything instead of LMDBAL::Transaction
+ *
+ * Active transactions become terminated upon the call of
+ * LMDBAL::WriteTransaction::abort or LMDBAL::WriteTransaction::commit.
+ * Calling LMDBAL::Transaction::terminate on LMDBAL::WriteTransaction
+ * is exactly the same as calling LMDBAL::WriteTransaction::abort.
+ *
+ * Active transactions automaticaly terminate themselves upon destruction.
+ * <b>For LMDBAL::WriteTransaction default behaviour upon destruction is to abort.</b>
+ *
+ * You <b>CAN NOT</b> use inactive transactions for any query.
+ */
+
+/**
+ * \brief Constructs active write transaction
+ */
 LMDBAL::WriteTransaction::WriteTransaction(TransactionID txn, Base* parent):
     Transaction(txn, parent)
 {}
 
+/**
+ * \brief Constructs inactive write transaction
+ */
 LMDBAL::WriteTransaction::WriteTransaction():
     Transaction()
 {}
 
+/**
+ * \brief Moves transaction to the new object
+ */
 LMDBAL::WriteTransaction::WriteTransaction(WriteTransaction&& other):
     Transaction(std::move(other))
 {}
 
+/**
+ * \brief Aborts transaction cancelling all changes
+ *
+ * Transaction becomes terminated after calling this method
+ */
 void LMDBAL::WriteTransaction::abort() {
     terminate();
 }
 
+/**
+ * \brief Commits transaction submitting all changes
+ *
+ * Transaction becomes terminated after calling this method
+ */
 void LMDBAL::WriteTransaction::commit() {
     if (active) {
         const_cast<Base*>(parent)->commitTransaction(txn);