finished documentation for Storage object, added doxygen awesome theme support

CMakeLists.txt

@@ -9,6 +9,7 @@ cmake_policy(SET CMP0079 NEW)
 option(BUILD_STATIC "Builds library as static library" OFF)
 option(BUILD_TESTS "Builds tests" OFF)
 option(BUILD_DOC "Builds documentation" OFF)
+option(BUILD_DOXYGEN_AWESOME "Builds documentation alternative style" OFF)
 
 include(GNUInstallDirs)
 include(CMakePackageConfigHelpers)

doc/CMakeLists.txt

@@ -1,6 +1,24 @@
 set(DOXYGEN_GENERATE_HTML YES)
 set(DOXYGEN_GENERATE_MAN YES)
 
+if (BUILD_DOXYGEN_AWESOME)
+    include(ExternalProject)
+    ExternalProject_Add(doxygen-awesome-css
+    GIT_REPOSITORY https://github.com/jothepro/doxygen-awesome-css.git
+    GIT_TAG "v2.2.0"
+    CONFIGURE_COMMAND ""
+    BUILD_COMMAND make
+    BUILD_IN_SOURCE TRUE
+    INSTALL_COMMAND make DESTDIR=${CMAKE_CURRENT_BINARY_DIR}/doxygen-awesome-css install
+    )
+    set (DOXYGEN_GENERATE_TREEVIEW YES)
+    set (DOXYGEN_DISABLE_INDEX NO)
+    set (DOXYGEN_FULL_SIDEBAR NO)
+    set (DOXYGEN_HTML_EXTRA_STYLESHEET ${CMAKE_CURRENT_BINARY_DIR}/doxygen-awesome-css/doxygen-awesome.css ${CMAKE_CURRENT_BINARY_DIR}/doxygen-awesome-css/doxygen-awesome-sidebar-only.css)
+    set (DOXYGEN_FULL_SIDEBAR NO)
+    set (DOXYGEN_HTML_COLORSTYLE "LIGHT")
+endif()
+
 doxygen_add_docs(
     documentation
     ${PROJECT_SOURCE_DIR}/src
@@ -8,3 +26,7 @@ doxygen_add_docs(
     ALL
     COMMENT "Generate man and html pages"
 )
+
+if (BUILD_DOXYGEN_AWESOME)
+    add_dependencies(documentation doxygen-awesome-css)
+endif()

src/storage.hpp

@@ -396,6 +396,14 @@ bool LMDBAL::Storage<K, V>::checkRecord(const K& key, TransactionID txn) const {
     return false;
 }
 
+/**
+ * \brief Reads whole storage into a map
+ *
+ * Basically just reads all database in an std::map, usefull when you store small storages
+ *
+ * \exception LMDBAL::Closed    thrown if the database was not opened
+ * \exception LMDBAL::Unknown   thrown if something unexpected happend within lmdb
+ */
 template<class K, class V>
 std::map<K, V> LMDBAL::Storage<K, V>::readAll() const {
     ensureOpened(readAllMethodName);
@@ -405,6 +413,16 @@ std::map<K, V> LMDBAL::Storage<K, V>::readAll() const {
     return result;
 }
 
+/**
+ * \brief Reads whole storage into a map (reference variant)
+ *
+ * Basically just reads all database in an std::map, usefull when you store small storages
+ *
+ * \param[out] result   a map that is going to contain all data
+ *
+ * \exception LMDBAL::Closed    thrown if the database was not opened
+ * \exception LMDBAL::Unknown   thrown if something unexpected happend within lmdb
+ */
 template<class K, class V>
 void LMDBAL::Storage<K, V>::readAll(std::map<K, V>& result) const {
     ensureOpened(readAllMethodName);
@@ -420,6 +438,18 @@ void LMDBAL::Storage<K, V>::readAll(std::map<K, V>& result) const {
     abortTransaction(txn);
 }
 
+/**
+ * \brief Reads whole storage into a map (transaction variant)
+ *
+ * Basically just reads all database in an std::map, usefull when you store small storages
+ * You can obtain LMDBAL::TransactionID calling LMDBAL::Base::beginReadOnlyTransaction() or LMDBAL::Base::beginTransaction().
+ * If you just want to read data you should prefer LMDBAL::Base::beginReadOnlyTransaction().
+ *
+ * \param[in] txn      transaction ID, can be read only transaction
+ *
+ * \exception LMDBAL::Closed    thrown if the database was not opened
+ * \exception LMDBAL::Unknown   thrown if something unexpected happend within lmdb
+ */
 template<class K, class V>
 std::map<K, V> LMDBAL::Storage<K, V>::readAll(TransactionID txn) const {
     ensureOpened(readAllMethodName);
@@ -429,6 +459,19 @@ std::map<K, V> LMDBAL::Storage<K, V>::readAll(TransactionID txn) const {
     return result;
 }
 
+/**
+ * \brief Reads whole storage into a map (transaction, reference variant)
+ *
+ * Basically just reads all database in an std::map, usefull when you store small storages
+ * You can obtain LMDBAL::TransactionID calling LMDBAL::Base::beginReadOnlyTransaction() or LMDBAL::Base::beginTransaction().
+ * If you just want to read data you should prefer LMDBAL::Base::beginReadOnlyTransaction().
+ *
+ * \param[out] result   a map that is going to contain all data
+ * \param[in] txn      transaction ID, can be read only transaction
+ *
+ * \exception LMDBAL::Closed    thrown if the database was not opened
+ * \exception LMDBAL::Unknown   thrown if something unexpected happend within lmdb
+ */
 template<class K, class V>
 void LMDBAL::Storage<K, V>::readAll(std::map<K, V>& result, TransactionID txn) const {
     ensureOpened(readAllMethodName);
@@ -453,6 +496,16 @@ void LMDBAL::Storage<K, V>::readAll(std::map<K, V>& result, TransactionID txn) c
         throwUnknown(rc);
 }
 
+/**
+ * \brief Replaces the content of the whole storage with the given
+ *
+ * Basically this function drops the database and adds all the records from the given map
+ *
+ * \param[in] data      new data of the storage
+ *
+ * \exception LMDBAL::Closed    thrown if the database was not opened
+ * \exception LMDBAL::Unknown   thrown if something unexpected happend within lmdb
+ */
 template<class K, class V>
 void LMDBAL::Storage<K, V>::replaceAll(const std::map<K, V>& data) {
     ensureOpened(replaceAllMethodName);
@@ -468,6 +521,19 @@ void LMDBAL::Storage<K, V>::replaceAll(const std::map<K, V>& data) {
     commitTransaction(txn);
 }
 
+/**
+ * \brief Replaces the content of the whole storage with the given (transaction variant)
+ *
+ * Basically this function drops the database and adds all the records from the given map
+ * This function schedules a data replacement, but doesn't immidiately execute it.
+ * You can obtain LMDBAL::TransactionID calling LMDBAL::Base::beginTransaction().
+ *
+ * \param[in] data      new data of the storage
+ * \param[in] txn       transaction ID, needs to be a writable transaction!
+ *
+ * \exception LMDBAL::Closed    thrown if the database was not opened
+ * \exception LMDBAL::Unknown   thrown if something unexpected happend within lmdb
+ */
 template<class K, class V>
 void LMDBAL::Storage<K, V>::replaceAll(const std::map<K, V>& data, TransactionID txn) {
     ensureOpened(replaceAllMethodName);
@@ -481,12 +547,23 @@ void LMDBAL::Storage<K, V>::replaceAll(const std::map<K, V>& data, TransactionID
         lmdbKey = keySerializer->setData(pair.first);
         lmdbData = valueSerializer->setData(pair.second);
 
-        rc = mdb_put(txn, dbi, &lmdbKey, &lmdbData, MDB_NOOVERWRITE);
+        rc = mdb_put(txn, dbi, &lmdbKey, &lmdbData, MDB_NOOVERWRITE);   //TODO may be appending with cursor makes sence here?
         if (rc != MDB_SUCCESS)
             throwUnknown(rc);
     }
 }
 
+/**
+ * \brief Adds records in bulk
+ *
+ * \param[in]       data        the data to be added
+ * \param[in]       overwrite   if false function throws LMDBAL::Exist on repeated key, if true - overwrites it
+ * \returns         new actual amount of records in the storage
+ *
+ * \exception LMDBAL::Closed    thrown if the database was not opened
+ * \exception LMDBAL::Exist     thrown if overwrite==false and at least one of the keys of data already exists in the storage
+ * \exception LMDBAL::Unknown   thrown if something unexpected happend within lmdb
+ */
 template<class K, class V>
 uint32_t LMDBAL::Storage<K, V>::addRecords(const std::map<K, V>& data, bool overwrite) {
     ensureOpened(addRecordsMethodName);
@@ -504,6 +581,21 @@ uint32_t LMDBAL::Storage<K, V>::addRecords(const std::map<K, V>& data, bool over
     return amount;
 }
 
+/**
+ * \brief Adds records in bulk (transaction variant)
+ *
+ * This function schedules a data addition, but doesn't immidiately execute it.
+ * You can obtain LMDBAL::TransactionID calling LMDBAL::Base::beginTransaction().
+ *
+ * \param[in]       data        the data to be added
+ * \param[in]       txn         transaction ID, needs to be a writable transaction!
+ * \param[in]       overwrite   if false function throws LMDBAL::Exist on repeated key, if true - overwrites it
+ * \returns         new actual amount of records in the storage
+ *
+ * \exception LMDBAL::Closed    thrown if the database was not opened
+ * \exception LMDBAL::Exist     thrown if overwrite==false and at least one of the keys of data already exists in the storage
+ * \exception LMDBAL::Unknown   thrown if something unexpected happend within lmdb
+ */
 template<class K, class V>
 uint32_t LMDBAL::Storage<K, V>::addRecords(const std::map<K, V>& data, TransactionID txn, bool overwrite) {
     ensureOpened(addRecordsMethodName);
@@ -530,6 +622,17 @@ uint32_t LMDBAL::Storage<K, V>::addRecords(const std::map<K, V>& data, Transacti
     return stat.ms_entries;
 }
 
+/**
+ * \brief Removes one of the records
+ *
+ * Take a note that if the storage didn't have a record you want to remove LMDBAL::NotFound is thrown
+ *
+ * \param[in]       key     key of the record you wish to be removed
+ *
+ * \exception LMDBAL::Closed    thrown if the database was not opened
+ * \exception LMDBAL::NotFound  thrown if the record with given key wasn't found
+ * \exception LMDBAL::Unknown   thrown if something unexpected happend within lmdb
+ */
 template<class K, class V>
 void LMDBAL::Storage<K, V>::removeRecord(const K& key) {
     ensureOpened(removeRecordMethodName);
@@ -545,6 +648,20 @@ void LMDBAL::Storage<K, V>::removeRecord(const K& key) {
     commitTransaction(txn);
 }
 
+/**
+ * \brief Removes one of the records (transaction variant)
+ *
+ * Take a note that if the storage didn't have a record you want to remove LMDBAL::NotFound is thrown
+ * This function schedules a record removal, but doesn't immidiately execute it.
+ * You can obtain LMDBAL::TransactionID calling LMDBAL::Base::beginTransaction().
+ *
+ * \param[in]       key     key of the record you wish to be removed
+ * \param[in]       txn         transaction ID, needs to be a writable transaction!
+ *
+ * \exception LMDBAL::Closed    thrown if the database was not opened
+ * \exception LMDBAL::NotFound  thrown if the record with given key wasn't found
+ * \exception LMDBAL::Unknown   thrown if something unexpected happend within lmdb
+ */
 template<class K, class V>
 void LMDBAL::Storage<K, V>::removeRecord(const K& key, TransactionID txn) {
     ensureOpened(removeRecordMethodName);
@@ -555,6 +672,13 @@ void LMDBAL::Storage<K, V>::removeRecord(const K& key, TransactionID txn) {
         throwNotFoundOrUnknown(rc, toString(key));
 }
 
+/**
+ * \brief A private virtual function I need to open database
+ *
+ * This and the following collection of specializations are a way to optimise database using
+ * MDB_INTEGERKEY flag, when the key is actually kind of an integer
+ * This infrastructure also allowes us to customize mdb_dbi_open call in the future
+ */
 template<class K, class V>
 int LMDBAL::Storage<K, V>::createStorage(MDB_txn* transaction) {
     return makeTable<K>(transaction);
@@ -605,6 +729,15 @@ inline int LMDBAL::iStorage::makeTable<int8_t>(MDB_txn* transaction) {
     return mdb_dbi_open(transaction, name.c_str(), MDB_CREATE | MDB_INTEGERKEY, &dbi);
 }
 
+/**
+ * \brief A method to cast a value (which can be a value or a key) to string.
+ *
+ * This function is mainly used in exceptions, to report which key was duplicated or not found.
+ * You can define your own specializations to this function in case std::to_string doesn't cover your case
+ *
+ * \param[in]   value   a value that should be converted to string
+ * \returns     a string presentation of value
+ */
 template<class T>
 inline std::string LMDBAL::iStorage::toString(const T& value) {
     return std::to_string(value);