documented iStorage, hosted docs and added readme link

README.md

@@ -3,6 +3,7 @@
 [![AUR license](https://img.shields.io/aur/license/lmdbal?style=flat-square)](https://git.macaw.me/blue/lmdbal/raw/branch/master/LICENSE.md)
 [![AUR version](https://img.shields.io/aur/version/lmdbal?style=flat-square)](https://aur.archlinux.org/packages/lmdbal/)
 [![Liberapay patrons](https://img.shields.io/liberapay/patrons/macaw.me?logo=liberapay&style=flat-square)](https://liberapay.com/macaw.me)
+[![Documentation](https://img.shields.io/badge/Documentation-HTLM-green)](https://macaw.me/lmdbal/doc/html)
 
 ### Prerequisites
 

src/base.cpp

@@ -33,13 +33,13 @@
 /**
  * \brief Creates the database
  *
- * \param[in] name      -   name of the database, it is going to affect folder name that is created to store data
+ * \param[in] _name      -   name of the database, it is going to affect folder name that is created to store data
- * \param[in] mapSize   -   LMDB map size (MBi), multiplied by 1024^2 and passed to <a class="el" href="http://www.lmdb.tech/doc/group__mdb.html#gaa2506ec8dab3d969b0e609cd82e619e5">mdb_env_set_mapsize</a> during the call of LMDBAL::Base::open()
+ * \param[in] _mapSize   -   LMDB map size (MBi), multiplied by 1024^2 and passed to <a class="el" href="http://www.lmdb.tech/doc/group__mdb.html#gaa2506ec8dab3d969b0e609cd82e619e5">mdb_env_set_mapsize</a> during the call of LMDBAL::Base::open()
  */
-LMDBAL::Base::Base(const QString& p_name, uint16_t mapSize):
+LMDBAL::Base::Base(const QString& _name, uint16_t _mapSize):
-    name(p_name.toStdString()),
+    name(_name.toStdString()),
     opened(false),
-    size(mapSize),
+    size(_mapSize),
     environment(),
     storages(),
     transactions(new Transactions())

src/base.h

@@ -114,7 +114,7 @@ private:
  * Defines that the database is going to have the following storage.
  * The LMDBAL::Base must be closed
  *
- * \param[in]   name    -   storage name
+ * \param[in]   _name    -   storage name
  * \returns     storage pointer. LMDBAL::Base keeps the ownership of the added storage, you don't need to destoroy it
  *
  * \tparam K    -   key type of the storage
@@ -124,14 +124,14 @@ private:
  * \exception LMDBAL::StorageDuplicate  thrown if somebody tries to add storage with repeating name
  */
 template <class K, class V>
-LMDBAL::Storage<K, V>* LMDBAL::Base::addStorage(const std::string& p_name) {
+LMDBAL::Storage<K, V>* LMDBAL::Base::addStorage(const std::string& _name) {
     if (opened) {
-        throw Opened(name, "add storage " + p_name);
+        throw Opened(name, "add storage " + _name);
     }
-    Storage<K, V>* storage = new Storage<K, V>(p_name, this);
+    Storage<K, V>* storage = new Storage<K, V>(_name, this);
-    std::pair<Storages::const_iterator, bool> pair = storages.insert(std::make_pair(p_name, (iStorage*)storage));
+    std::pair<Storages::const_iterator, bool> pair = storages.insert(std::make_pair(_name, (iStorage*)storage));
     if (!pair.second)
-        throw StorageDuplicate(name, p_name);
+        throw StorageDuplicate(name, _name);
 
     return storage;
 }
@@ -142,7 +142,7 @@ LMDBAL::Storage<K, V>* LMDBAL::Base::addStorage(const std::string& p_name) {
  * Defines that the database is going to have the following cache.
  * The LMDBAL::Base must be closed
  *
- * \param[in]   name    -   cache name
+ * \param[in]   _name    -   cache name
  * \returns     cache pointer. LMDBAL::Base keeps the ownership of the added cache, you don't need to destoroy it
  *
  * \tparam K    -   key type of the cache
@@ -152,14 +152,14 @@ LMDBAL::Storage<K, V>* LMDBAL::Base::addStorage(const std::string& p_name) {
  * \exception LMDBAL::StorageDuplicate  thrown if somebody tries to add cache with repeating name
  */
 template<class K, class V>
-LMDBAL::Cache<K, V> * LMDBAL::Base::addCache(const std::string& p_name) {
+LMDBAL::Cache<K, V> * LMDBAL::Base::addCache(const std::string& _name) {
     if (opened) {
-        throw Opened(name, "add cache " + p_name);
+        throw Opened(name, "add cache " + _name);
     }
-    Cache<K, V>* cache = new Cache<K, V>(p_name, this);
+    Cache<K, V>* cache = new Cache<K, V>(_name, this);
-    std::pair<Storages::const_iterator, bool> pair = storages.insert(std::make_pair(p_name, (iStorage*)cache));
+    std::pair<Storages::const_iterator, bool> pair = storages.insert(std::make_pair(_name, (iStorage*)cache));
     if (!pair.second)
-        throw StorageDuplicate(name, p_name);
+        throw StorageDuplicate(name, _name);
 
     return cache;
 }
@@ -173,7 +173,7 @@ LMDBAL::Cache<K, V> * LMDBAL::Base::addCache(const std::string& p_name) {
  * this method with template parameters <std::string, std::string>
  * on the same name of the previously added storage, or calling it on cache - the behaviour is undefined
  *
- * \param[in]   name    -   storage name
+ * \param[in]   _name    -   storage name
  * \returns     storage pointer. LMDBAL::Base keeps the ownership of the added storage, you don't need to destoroy it
  *
  * \tparam K    -   key type of the storage
@@ -182,8 +182,8 @@ LMDBAL::Cache<K, V> * LMDBAL::Base::addCache(const std::string& p_name) {
  * \exception std::out_of_range thrown if storage with the given name was not found
  */
 template <class K, class V>
-LMDBAL::Storage<K, V>* LMDBAL::Base::getStorage(const std::string& p_name) {
+LMDBAL::Storage<K, V>* LMDBAL::Base::getStorage(const std::string& _name) {
-    return static_cast<Storage<K, V>*>(storages.at(p_name));
+    return static_cast<Storage<K, V>*>(storages.at(_name));
 }
 
 /**
@@ -195,7 +195,7 @@ LMDBAL::Storage<K, V>* LMDBAL::Base::getStorage(const std::string& p_name) {
  * this method with template parameters <std::string, std::string>
  * on the same name of the previously added cache, or calling it on storage - the behaviour is undefined
  *
- * \param[in]   name    -   cache name
+ * \param[in]   _name    -   cache name
  * \returns     cache pointer. LMDBAL::Base keeps the ownership of the added cache, you don't need to destoroy it
  *
  * \tparam K    -   key type of the cache
@@ -204,8 +204,8 @@ LMDBAL::Storage<K, V>* LMDBAL::Base::getStorage(const std::string& p_name) {
  * \exception std::out_of_range thrown if cache with the given name was not found
  */
 template <class K, class V>
-LMDBAL::Cache<K, V>* LMDBAL::Base::getCache(const std::string& p_name) {
+LMDBAL::Cache<K, V>* LMDBAL::Base::getCache(const std::string& _name) {
-    return static_cast<Cache<K, V>*>(storages.at(p_name));
+    return static_cast<Cache<K, V>*>(storages.at(_name));
 }
 
 #endif //LMDBAL_BASE_H

src/storage.cpp

@@ -20,14 +20,36 @@
 
 #define UNUSED(x) (void)(x)
 
+/**
+ * \class LMDBAL::iStorage
+ *
+ * This is a interface-like class, it's designed to be an inner database interface to
+ * be used as a polymorphic entity, and provide protected interaction with the database
+ * from the heirs code
+ */
+
+/**
+ * \brief Constructs a storage interface
+ */
 LMDBAL::iStorage::iStorage(const std::string& p_name, Base* parent):
     dbi(),
     db(parent),
     name(p_name)
 {}
 
+/**
+ * \brief Destroys a storage interface
+ */
 LMDBAL::iStorage::~iStorage() {}
 
+/**
+ * \brief Drops content of a storage interface
+ *
+ * Designed to drop storage content
+ *
+ * \exception LMDBAL::Closed    thrown if the database was closed
+ * \exception LMDBAL::Unknown   thrown if something unexpected happened
+ */
 void LMDBAL::iStorage::drop() {
     ensureOpened(dropMethodName);
 
@@ -41,15 +63,38 @@ void LMDBAL::iStorage::drop() {
     db->commitTransaction(txn);
 }
 
+/**
+ * \brief Drops content of a storage interface (transaction variant)
+ *
+ * Just performs content drop
+ *
+ * \param[in] transaction   - transaction ID, must be writable transaction!
+ * \returns MDB_SUCCESS if everything went fine, MDB_<error> code otherwise
+ */
 int LMDBAL::iStorage::drop(TransactionID transaction) {
     return mdb_drop(transaction, dbi, 0);
 }
 
+/**
+ * \brief Helper function, thows exception if the database is not opened
+ *
+ * \param[in] methodName    - name of the method this function is called from, just for display in std::exception::what() message
+ *
+ * \exception LMDBAL::Closed    thrown if the database was closed
+ */
 void LMDBAL::iStorage::ensureOpened(const std::string& methodName) const {
-    if (!db->opened)
+    if (!isDBOpened())
         throw Closed(methodName, db->name, name);
 }
 
+/**
+ * \brief Storage size
+ *
+ * \returns amount of records in the storage
+ *
+ * \exception LMDBAL::Closed    thrown if the database was closed
+ * \exception LMDBAL::Unknown   thrown if something unexpected happened
+ */
 LMDBAL::SizeType LMDBAL::iStorage::count() const {
     ensureOpened(countMethodName);
 
@@ -66,6 +111,14 @@ LMDBAL::SizeType LMDBAL::iStorage::count() const {
     return amount;
 }
 
+/**
+ * \brief Storage size (transaction variant)
+ *
+ * \param[in] txn   - transaction ID, can be read-only transaction
+ * \returns amount of records in the storage
+ *
+ * \exception LMDBAL::Unknown   thrown if something unexpected happened
+ */
 LMDBAL::SizeType LMDBAL::iStorage::count(TransactionID txn) const {
     MDB_stat stat;
     int rc = mdb_stat(txn, dbi, &stat);
@@ -75,16 +128,51 @@ LMDBAL::SizeType LMDBAL::iStorage::count(TransactionID txn) const {
     return stat.ms_entries;
 }
 
+/**
+ * \brief Throws LMDBAL::Exist or LMDBAL::Unknown (transaction vairiant)
+ *
+ * Helper function ment to be used in heirs and reduce the code a bit
+ *
+ * \param[in] rc    - result of lmdb low level operation
+ * \param[in] txn   - transaction ID to be aborted, any transaction
+ * \param[in] key   - requested key string representation, just to show in std::exception::what() message
+ *
+ * \exception LMDBAL::Exist     thrown if rc == MDB_KEYEXIST
+ * \exception LMDBAL::Unknown   thrown if rc != MDB_KEYEXIST
+ */
 void LMDBAL::iStorage::throwDuplicateOrUnknown(int rc, TransactionID txn, const std::string& key) const {
     abortTransaction(txn);
     throwDuplicateOrUnknown(rc, key);
 }
 
+/**
+ * \brief Throws LMDBAL::NotFound or LMDBAL::Unknown (transaction vairiant)
+ *
+ * Helper function ment to be used in heirs and reduce the code a bit
+ *
+ * \param[in] rc    - result of lmdb low level operation
+ * \param[in] txn   - transaction ID to be aborted, any transaction
+ * \param[in] key   - requested key string representation, just to show in std::exception::what() message
+ *
+ * \exception LMDBAL::NotFound  thrown if rc == MDB_NOTFOUND
+ * \exception LMDBAL::Unknown   thrown if rc != MDB_NOTFOUND
+ */
 void LMDBAL::iStorage::throwNotFoundOrUnknown(int rc, LMDBAL::TransactionID txn, const std::string& key) const {
     abortTransaction(txn);
     throwNotFoundOrUnknown(rc, key);
 }
 
+/**
+ * \brief Throws LMDBAL::Exist or LMDBAL::Unknown
+ *
+ * Helper function ment to be used in heirs and reduce the code a bit
+ *
+ * \param[in] rc    - result of lmdb low level operation
+ * \param[in] key   - requested key string representation, just to show in std::exception::what() message
+ *
+ * \exception LMDBAL::Exist     thrown if rc == MDB_KEYEXIST
+ * \exception LMDBAL::Unknown   thrown if rc != MDB_KEYEXIST
+ */
 void LMDBAL::iStorage::throwDuplicateOrUnknown(int rc, const std::string& key) const {
     if (rc == MDB_KEYEXIST)
         throwDuplicate(key);
@@ -92,6 +180,17 @@ void LMDBAL::iStorage::throwDuplicateOrUnknown(int rc, const std::string& key) c
         throwUnknown(rc);
 }
 
+/**
+ * \brief Throws LMDBAL::NotFound or LMDBAL::Unknown (transaction variant)
+ *
+ * Helper function ment to be used in heirs and reduce the code a bit
+ *
+ * \param[in] rc    - result of lmdb low level operation
+ * \param[in] key   - requested key string representation, just to show in std::exception::what() message
+ *
+ * \exception LMDBAL::NotFound  thrown if rc == MDB_NOTFOUND
+ * \exception LMDBAL::Unknown   thrown if rc != MDB_NOTFOUND
+ */
 void LMDBAL::iStorage::throwNotFoundOrUnknown(int rc, const std::string& key) const {
     if (rc == MDB_NOTFOUND)
         throwNotFound(key);
@@ -99,45 +198,157 @@ void LMDBAL::iStorage::throwNotFoundOrUnknown(int rc, const std::string& key) co
         throwUnknown(rc);
 }
 
+/**
+ * \brief Throws LMDBAL::Unknown (transaction vairiant)
+ *
+ * Helper function ment to be used in heirs and reduce the code a bit
+ *
+ * \param[in] rc    - result of lmdb low level operation
+ * \param[in] txn   - transaction ID to be aborted, any transaction
+ *
+ * \exception LMDBAL::Unknown   thrown everytime
+ */
 void LMDBAL::iStorage::throwUnknown(int rc, LMDBAL::TransactionID txn) const {
     abortTransaction(txn);
     throwUnknown(rc);
 }
 
+/**
+ * \brief Database name
+ *
+ * Ment to be used in heirs, to provide some sort of interface to acces to some of the database information
+ *
+ * \returns database name
+ */
 const std::string & LMDBAL::iStorage::dbName() const {
     return db->name;}
 
+/**
+ * \brief Is database opened
+ *
+ * Ment to be used in heirs, to provide some sort of interface to acces to some of the database information
+ *
+ * \returns true if database is ipened, false otherwise
+ */
 bool LMDBAL::iStorage::isDBOpened() const {
     return db->opened;}
 
+/**
+ * \brief Throws LMDBAL::Unknown
+ *
+ * Helper function ment to be used in heirs and reduce the code a bit
+ *
+ * \param[in] rc    - result of lmdb low level operation
+ *
+ * \exception LMDBAL::Unknown   thrown everytime
+ */
 void LMDBAL::iStorage::throwUnknown(int rc) const {
     throw Unknown(db->name, mdb_strerror(rc), name);}
 
+/**
+ * \brief Throws LMDBAL::Exist
+ *
+ * Helper function ment to be used in heirs and reduce the code a bit
+ *
+ * \param[in] key   - requested key string representation, just to show in std::exception::what() message
+ *
+ * \exception LMDBAL::Exist   thrown everytime
+ */
 void LMDBAL::iStorage::throwDuplicate(const std::string& key) const {
     throw Exist(key, db->name, name);}
 
+/**
+ * \brief Throws LMDBAL::NotFound
+ *
+ * Helper function ment to be used in heirs and reduce the code a bit
+ *
+ * \param[in] key   - requested key string representation, just to show in std::exception::what() message
+ *
+ * \exception LMDBAL::NotFound   thrown everytime
+ */
 void LMDBAL::iStorage::throwNotFound(const std::string& key) const {
     throw NotFound(key, db->name, name);}
 
+/**
+ * \brief Begins read-only transaction
+ *
+ * Ment to be called from heirs, name is reported to the database just to be displayed in std::exception::what() message
+ *
+ * \returns read only transaction
+ */
 LMDBAL::TransactionID LMDBAL::iStorage::beginReadOnlyTransaction() const {
     return db->beginPrivateReadOnlyTransaction(name);}
 
+/**
+ * \brief Begins writable transaction
+ *
+ * Ment to be called from heirs, name is reported to the database just to be displayed in std::exception::what() message
+ *
+ * \returns read only transaction
+ */
 LMDBAL::TransactionID LMDBAL::iStorage::beginTransaction() const {
     return db->beginPrivateTransaction(name);}
 
+/**
+ * \brief Aborts transaction
+ *
+ * Ment to be called from heirs, name is reported to the database just to be displayed in std::exception::what() message
+ */
 void LMDBAL::iStorage::abortTransaction(LMDBAL::TransactionID id) const {
     db->abortPrivateTransaction(id, name);}
 
+/**
+ * \brief Commits transaction
+ *
+ * Ment to be called from heirs, name is reported to the database just to be displayed in std::exception::what() message
+ *
+ * \exception LMDBAL::Unknown   thrown if something unexpected happened
+ */
 void LMDBAL::iStorage::commitTransaction(LMDBAL::TransactionID id) {
     db->commitPrivateTransaction(id, name);}
 
+/**
+ * \brief called on beginning of public transaction
+ *
+ * This function is called on every storage of the database
+ * when user calls LMDBAL::Base::beginTransaction() or LMDBAL::Base::beginReadOnlyTransaction()
+ *
+ * This function is met to be reimplemented in heirs
+ * if the heir code requires some transaction custom handling
+ *
+ * \param[in] txn       - ID of started transaction
+ * \param[in] readOnly  - true if transaction is read-only, false otherwise
+ */
 void LMDBAL::iStorage::transactionStarted(LMDBAL::TransactionID txn, bool readOnly) const {
     UNUSED(txn);
     UNUSED(readOnly);
 }
+
+/**
+ * \brief called on commitment of public transaction
+ *
+ * This function is called on every storage of the database
+ * when user calls LMDBAL::Base::commitTransaction(LMDBAL::TransactionID)
+ *
+ * This function is met to be reimplemented in heirs
+ * if the heir code requires some transaction custom handling
+ *
+ * \param[in] txn       - ID of started transaction
+ */
 void LMDBAL::iStorage::transactionCommited(LMDBAL::TransactionID txn) {
     UNUSED(txn);}
 
+/**
+ * \brief called on abortion of public transaction
+ *
+ * This function is called on every storage of the database
+ * when user calls LMDBAL::Base::abortTransaction(LMDBAL::TransactionID)
+ *
+ * This function is met to be reimplemented in heirs
+ * if the heir code requires some transaction custom handling
+ *
+ * \param[in] txn       - ID of started transaction
+ */
 void LMDBAL::iStorage::transactionAborted(LMDBAL::TransactionID txn) const {
     UNUSED(txn);}