From ed0e0791506a937f36cae8d966abdc708c16cdaf Mon Sep 17 00:00:00 2001 From: Emily Boudreaux Date: Thu, 20 Mar 2025 14:37:15 -0400 Subject: [PATCH] docs(src): added documentation to all changes related to the resource manager --- src/eos/public/eosIO.h | 46 ++++++++++++-- src/misc/macros/debug.h | 25 ++++++++ src/resource/public/resourceManager.h | 74 +++++++++++++++++++++- src/resource/public/resourceManagerTypes.h | 51 ++++++++++++++- 4 files changed, 187 insertions(+), 9 deletions(-) diff --git a/src/eos/public/eosIO.h b/src/eos/public/eosIO.h index 4087f9f..aab0c59 100644 --- a/src/eos/public/eosIO.h +++ b/src/eos/public/eosIO.h @@ -12,22 +12,58 @@ using EOSTable = std::variant< std::unique_ptr >; +/** + * @class EosIO + * @brief Handles the input/output operations for EOS tables. + * + * The EosIO class is responsible for loading and managing EOS tables from files. + * It supports different formats, currently only HELM format. + * + * Example usage: + * @code + * EosIO eosIO("path/to/file"); + * std::string format = eosIO.getFormat(); + * EOSTable& table = eosIO.getTable(); + * @endcode + */ class EosIO { private: - std::string m_filename; - bool m_loaded = false; - std::string m_format; - EOSTable m_table; + std::string m_filename; ///< The filename of the EOS table. + bool m_loaded = false; ///< Flag indicating if the table is loaded. + std::string m_format; ///< The format of the EOS table. + EOSTable m_table; ///< The EOS table data. + + /** + * @brief Loads the EOS table from the file. + */ void load(); - // Loaders for each format, right now just HELM + /** + * @brief Loads the HELM format EOS table. + */ void loadHelm(); public: + /** + * @brief Constructs an EosIO object with the given filename. + * @param filename The filename of the EOS table. + */ EosIO(const std::string filename); + + /** + * @brief Default destructor. + */ ~EosIO() = default; + /** + * @brief Gets the format of the EOS table. + * @return The format of the EOS table as a string. + */ std::string getFormat() const; + /** + * @brief Gets the EOS table. + * @return A reference to the EOS table. + */ EOSTable& getTable(); }; diff --git a/src/misc/macros/debug.h b/src/misc/macros/debug.h index b0f7d5b..284268d 100644 --- a/src/misc/macros/debug.h +++ b/src/misc/macros/debug.h @@ -1,11 +1,36 @@ +/** + * @file debug.h + * @brief Defines a macro for triggering a breakpoint in different compilers and platforms. + * + * This file provides a macro `BREAKPOINT()` that triggers a breakpoint + * in the debugger, depending on the compiler and platform being used. + * + * Usage: + * @code + * BREAKPOINT(); // Triggers a breakpoint in the debugger + * @endcode + */ + #ifdef __GNUC__ // GCC and Clang + /** + * @brief Triggers a breakpoint in GCC and Clang. + */ #define BREAKPOINT() __builtin_debugtrap() #elif defined(_MSC_VER) // MSVC + /** + * @brief Triggers a breakpoint in MSVC. + */ #define BREAKPOINT() __debugbreak() #elif defined(__APPLE__) && defined(__MACH__) // macOS with Clang and LLDB #include + /** + * @brief Triggers a breakpoint in macOS with Clang and LLDB. + */ #define BREAKPOINT() raise(SIGTRAP) #else #include + /** + * @brief Triggers a breakpoint in other platforms. + */ #define BREAKPOINT() std::raise(SIGTRAP) #endif diff --git a/src/resource/public/resourceManager.h b/src/resource/public/resourceManager.h index b304d4c..6c34635 100644 --- a/src/resource/public/resourceManager.h +++ b/src/resource/public/resourceManager.h @@ -11,11 +11,30 @@ #include "probe.h" #include "quill/LogMacros.h" +/** + * @class ResourceManager + * @brief Manages resources within the application. + * + * The ResourceManager class is responsible for loading, storing, and providing access to resources. + * It follows the Singleton design pattern to ensure only one instance of the manager exists. + */ class ResourceManager { private: + /** + * @brief Private constructor to prevent instantiation. + */ ResourceManager(); + + /** + * @brief Deleted copy constructor to prevent copying. + */ ResourceManager(const ResourceManager&) = delete; + + /** + * @brief Deleted assignment operator to prevent assignment. + */ ResourceManager& operator=(const ResourceManager&) = delete; + Config& m_config = Config::getInstance(); Probe::LogManager& m_logManager = Probe::LogManager::getInstance(); quill::Logger* m_logger = m_logManager.getLogger("log"); @@ -24,24 +43,73 @@ private: std::string m_dataDir; std::unordered_map m_resources; + /** + * @brief Loads a resource by name. + * @param name The name of the resource to load. + * @return True if the resource was loaded successfully, false otherwise. + */ bool load(const std::string& name); public: + /** + * @brief Gets the singleton instance of the ResourceManager. + * @return The singleton instance of the ResourceManager. + */ static ResourceManager& getInstance() { static ResourceManager instance; return instance; } + /** + * @brief Gets a list of available resources. + * @return A vector of strings containing the names of available resources. + * + * Example usage: + * @code + * ResourceManager& manager = ResourceManager::getInstance(); + * std::vector resources = manager.getAvaliableResources(); + * @endcode + */ std::vector getAvaliableResources(); + /** + * @brief Gets a resource by name. + * @param name The name of the resource to retrieve. + * @return A constant reference to the requested resource. + * @throws std::runtime_error if the resource is not found. + * + * Example usage: + * @code + * ResourceManager& manager = ResourceManager::getInstance(); + * const Resource& resource = manager.getResource("exampleResource"); + * @endcode + */ const Resource& getResource(const std::string &name) const; + /** + * @brief Loads a resource by name. + * @param name The name of the resource to load. + * @return True if the resource was loaded successfully, false otherwise. + * + * Example usage: + * @code + * ResourceManager& manager = ResourceManager::getInstance(); + * bool success = manager.loadResource("exampleResource"); + * @endcode + */ bool loadResource(std::string& name); + /** + * @brief Loads all resources. + * @return An unordered map with resource names as keys and load success as values. + * + * Example usage: + * @code + * ResourceManager& manager = ResourceManager::getInstance(); + * std::unordered_map results = manager.loadAllResources(); + * @endcode + */ std::unordered_map loadAllResources(); - - }; - #endif // RESOURCE_MANAGER_H \ No newline at end of file diff --git a/src/resource/public/resourceManagerTypes.h b/src/resource/public/resourceManagerTypes.h index e0b343e..7700e03 100644 --- a/src/resource/public/resourceManagerTypes.h +++ b/src/resource/public/resourceManagerTypes.h @@ -9,14 +9,63 @@ #include "meshIO.h" #include "eosIO.h" +/** + * @file resourceManagerTypes.h + * @brief Defines types and functions for managing resources. + * + * This file provides type definitions and functions for handling different + * types of resources in a unified manner. + */ + // -- Valid resource types +/** + * @brief A variant type that can hold different types of resources. + * + * The Resource type is a std::variant that can hold a unique pointer to + * an OpatIO, MeshIO, or EosIO object. + * + * Example usage: + * @code + * Resource resource = std::make_unique(...); + * @endcode + */ using Resource = std::variant< std::unique_ptr, std::unique_ptr, std::unique_ptr>; - +/** + * @brief Extracts the first segment of a given string. + * + * This function takes a string input and returns the first segment + * separated by a delimiter (default is '/'). + * + * @param input The input string to be processed. + * @return The first segment of the input string. + * + * Example usage: + * @code + * std::string segment = getFirstSegment("path/to/resource"); + * // segment == "path" + * @endcode + */ std::string getFirstSegment(const std::string& input); + +/** + * @brief Creates a resource based on the specified type and path. + * + * This function creates a resource object based on the provided type + * and initializes it using the given path. + * + * @param type The type of the resource to be created (e.g., "OpatIO", "MeshIO", "EosIO"). + * @param path The path to initialize the resource with. + * @return A Resource object initialized with the specified type and path. + * + * Example usage: + * @code + * Resource resource = createResource("OpatIO", "path/to/opat"); + * @endcode + */ Resource createResource(const std::string& type, const std::string& path); #endif // RESOURCE_MANAGER_TYPES_H \ No newline at end of file