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

src/base.cpp

@@ -216,6 +216,14 @@ void LMDBAL::Base::drop() {
 /**
  * \brief Begins read-only transaction
  *
+ * This is the legitimate way to retrieve LMDBAL::Transaction.
+ * LMDBAL::Transaction is considered runnig right after creation by this method.
+ * You can terminate transaction manually calling LMDBAL::Transaction::terminate
+ * but it's not required, because transaction will be terminated automatically
+ * (if it was not terminated manually) upon the call of the destructor.
+ *
+ * You can not use termitated transaction any more.
+ *
  * \returns read-only transaction
  *
  * \exception LMDBAL::Closed    - thrown if the database is closed
@@ -229,6 +237,16 @@ LMDBAL::Transaction LMDBAL::Base::beginReadOnlyTransaction() const {
 /**
  * \brief Begins writable transaction
  *
+ * This is the legitimate way to retrieve LMDBAL::WriteTransaction.
+ * LMDBAL::WriteTransaction is considered runnig right after creation by this method.
+ * You can commit all the changes made by this transaction calling LMDBAL::WriteTransaction::commit.
+ * You can cancel any changes made bu this transaction calling LMDBAL::WriteTransaction::abort
+ * (or LMDBAL::Transaction::terminate which LMDBAL::WriteTransaction inherits),
+ * but it's not required, because transaction will be aborted automatically
+ * (if it was not terminated (committed <b>OR</b> aborted) manually) upon the call of the destructor.
+ *
+ * You can not use termitated transaction any more.
+ *
  * \returns writable transaction
  *
  * \exception LMDBAL::Closed    - thrown if the database is closed

src/cursor.hpp

@@ -186,7 +186,7 @@ void LMDBAL::Cursor<K, V>::renew () const {
  *
  * This function does nothing if the cursor is closed
  *
- * \param[in]   txn         a transaction you wish this cursor to be bound to
+ * \param[in]   transaction     - a transaction you wish this cursor to be bound to
  *
  * \exception LMDBAL::Closed                thrown if you try to renew the cursor on a closed database
  * \exception LMDBAL::Unknown               thrown if there was a problem renewing the cursor by lmdb

src/storage.cpp

@@ -439,4 +439,10 @@ void LMDBAL::iStorage::transactionCommited(LMDBAL::TransactionID txn) {
 void LMDBAL::iStorage::transactionAborted(LMDBAL::TransactionID txn) const {
     UNUSED(txn);}
 
+/**
+ * \brief A method where database additionally handles drop
+ *
+ * It's a protected method that is called to optimise drop process
+ * after the transaction is commited. Used just for optimisations.
+ */
 void LMDBAL::iStorage::handleDrop() {}

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);

src/transaction.h

@@ -23,9 +23,9 @@ protected:
     Transaction(TransactionID txn, const Base* parent);
 
 protected:
-    TransactionID txn;
-    bool active;
-    const Base* parent;
+    TransactionID txn;          /**<\brief Transaction inner handler*/
+    bool active;                /**<\brief Transaction state*/
+    const Base* parent;         /**<\brief Pointer to the database this transaction belongs to*/
 };
 
 class WriteTransaction : public Transaction {