From ec0d2d57f09c40f6270aaae51e27e7d5abc953b3 Mon Sep 17 00:00:00 2001 From: blue Date: Sun, 9 Apr 2023 14:19:23 -0300 Subject: [PATCH] finished documentation for Storage object, added doxygen awesome theme support --- CMakeLists.txt | 1 + doc/CMakeLists.txt | 22 ++++++++ src/storage.hpp | 135 ++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 157 insertions(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index fbbeb34..d56e05d 100644 --- a/CMakeLists.txt +++ b/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) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 4998bb0..1626a47 100644 --- a/doc/CMakeLists.txt +++ b/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() diff --git a/src/storage.hpp b/src/storage.hpp index 6818552..f46ebd8 100644 --- a/src/storage.hpp +++ b/src/storage.hpp @@ -396,6 +396,14 @@ bool LMDBAL::Storage::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 std::map LMDBAL::Storage::readAll() const { ensureOpened(readAllMethodName); @@ -405,6 +413,16 @@ std::map LMDBAL::Storage::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 void LMDBAL::Storage::readAll(std::map& result) const { ensureOpened(readAllMethodName); @@ -420,6 +438,18 @@ void LMDBAL::Storage::readAll(std::map& 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 std::map LMDBAL::Storage::readAll(TransactionID txn) const { ensureOpened(readAllMethodName); @@ -429,6 +459,19 @@ std::map LMDBAL::Storage::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 void LMDBAL::Storage::readAll(std::map& result, TransactionID txn) const { ensureOpened(readAllMethodName); @@ -453,6 +496,16 @@ void LMDBAL::Storage::readAll(std::map& 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 void LMDBAL::Storage::replaceAll(const std::map& data) { ensureOpened(replaceAllMethodName); @@ -468,6 +521,19 @@ void LMDBAL::Storage::replaceAll(const std::map& 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 void LMDBAL::Storage::replaceAll(const std::map& data, TransactionID txn) { ensureOpened(replaceAllMethodName); @@ -481,12 +547,23 @@ void LMDBAL::Storage::replaceAll(const std::map& 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 uint32_t LMDBAL::Storage::addRecords(const std::map& data, bool overwrite) { ensureOpened(addRecordsMethodName); @@ -504,6 +581,21 @@ uint32_t LMDBAL::Storage::addRecords(const std::map& 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 uint32_t LMDBAL::Storage::addRecords(const std::map& data, TransactionID txn, bool overwrite) { ensureOpened(addRecordsMethodName); @@ -530,6 +622,17 @@ uint32_t LMDBAL::Storage::addRecords(const std::map& 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 void LMDBAL::Storage::removeRecord(const K& key) { ensureOpened(removeRecordMethodName); @@ -545,6 +648,20 @@ void LMDBAL::Storage::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 void LMDBAL::Storage::removeRecord(const K& key, TransactionID txn) { ensureOpened(removeRecordMethodName); @@ -555,6 +672,13 @@ void LMDBAL::Storage::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 int LMDBAL::Storage::createStorage(MDB_txn* transaction) { return makeTable(transaction); @@ -605,6 +729,15 @@ inline int LMDBAL::iStorage::makeTable(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 inline std::string LMDBAL::iStorage::toString(const T& value) { return std::to_string(value);