doc: add doxygen comment for code

src/yycc/carton/binstore.hpp

@@ -5,4 +5,25 @@
 #include "binstore/configuration.hpp"
 #include "binstore/storage.hpp"
 
+/**
+ * @brief The main namespace for the binstore module.
+ * @details
+ * The binstore module provides a binary settings storage system that allows
+ * applications to persistently store and retrieve configuration settings in
+ * a binary format. It includes functionality for:
+ * 
+ * \li Type-safe serialization and deserialization of various data types
+ *     (integers, floating-point numbers, booleans, strings, enums)
+ * \li Setting management with unique tokens for access control
+ * \li Version control for configuration data with migration strategies
+ * \li File and stream-based storage operations
+ * \li Comprehensive error handling for robust operation
+ * 
+ * The main components are:
+ * \li types: Basic types and error handling for the module
+ * \li serdes: Serialization/deserialization functionality for different data types
+ * \li setting: Management of settings with name-based lookup and token-based access
+ * \li configuration: Version and settings collection management
+ * \li storage: Main storage class for loading/saving settings to/from files or streams
+ */
 namespace yycc::carton::binstore {}

src/yycc/carton/binstore/configuration.hpp

@@ -8,14 +8,28 @@
 
 namespace yycc::carton::binstore::configuration {
 
+    /// @brief Configuration class that holds version and settings for the binstore module.
     class Configuration {
     public:
+        /**
+         * @brief Construct a new Configuration object.
+         * @param[in] version The version identifier for this configuration.
+         * @param[in] settings The settings collection to associate with this configuration.
+         */
         Configuration(NS_YYCC_BINSTORE_TYPES::VersionIdentifier version, NS_YYCC_BINSTORE::setting::SettingCollection&& settings);
         ~Configuration();
         YYCC_DEFAULT_COPY_MOVE(Configuration)
 
     public:
+        /**
+         * @brief Get the version identifier of this configuration.
+         * @return The version identifier.
+         */
         NS_YYCC_BINSTORE_TYPES::VersionIdentifier get_version() const;
+        /**
+         * @brief Get the settings collection associated with this configuration.
+         * @return A const reference to the settings collection.
+         */
         const NS_YYCC_BINSTORE::setting::SettingCollection& get_settings() const;
 
     private:

src/yycc/carton/binstore/setting.hpp

@@ -1,3 +1,7 @@
+/**
+ * @file setting.hpp
+ * @brief Setting management for the binstore module.
+ */
 #pragma once
 #include "../../macro/class_copy_move.hpp"
 #include "types.hpp"
@@ -11,47 +15,107 @@
 
 namespace yycc::carton::binstore::setting {
 
+    /// @brief Represents a single setting with a name.
     class Setting {
     public:
+        /**
+         * @brief Construct a new Setting object.
+         * @param[in] name The name of the setting.
+         */
         Setting(const std::u8string_view& name);
         ~Setting();
         YYCC_DEFAULT_COPY_MOVE(Setting)
 
     public:
+        /**
+         * @brief Get the name of the setting.
+         * @return A u8string_view of the setting name.
+         */
         std::u8string_view get_name() const;
 
     private:
         std::u8string name;
     };
 
+    /// @brief Represents a registered setting with both a token and setting information.
     class RegisteredSetting {
     public:
+        /**
+         * @private
+         * @brief Construct a new Registered Setting object.
+         * @param[in] token The unique token for the setting.
+         * @param[in] setting The setting information.
+         */
         RegisteredSetting(NS_YYCC_BINSTORE_TYPES::Token token, Setting&& setting);
         ~RegisteredSetting();
         YYCC_DEFAULT_COPY_MOVE(RegisteredSetting)
 
     public:
+        /**
+         * @brief Get the token associated with this registered setting.
+         * @return The token.
+         */
         NS_YYCC_BINSTORE_TYPES::Token get_token() const;
+
+        /**
+         * @brief Get the setting instance associated with this registered setting.
+         * @return A const reference to the setting.
+         */
         const Setting& get_setting() const;
 
     private:
-        NS_YYCC_BINSTORE_TYPES::Token token;
+        NS_YYCC_BINSTORE_TYPES::Token token; ///< The unique token for the setting.
-        Setting setting;
+        Setting setting;                     ///< The setting instance.
     };
 
+    /// @brief Collection of settings with name-based lookup and token-based access.
     class SettingCollection {
     public:
+        /// @brief Construct a new Setting Collection object.
         SettingCollection();
         ~SettingCollection();
         YYCC_DEFAULT_COPY_MOVE(SettingCollection)
 
     public:
+        /**
+         * @brief Add a setting to the collection.
+         * @param[in] setting The setting to add.
+         * @return The token assigned to the setting.
+         */
         NS_YYCC_BINSTORE_TYPES::Token add_setting(Setting&& setting);
+        /**
+         * @brief Find a setting by its name.
+         * @param[in] name The name of the setting to find.
+         * @return An optional token if the setting was found, std::nullopt otherwise.
+         */
         std::optional<NS_YYCC_BINSTORE_TYPES::Token> find_name(const std::u8string_view& name) const;
+        /**
+         * @brief Check if a setting with the given token exists.
+         * @param[in] token The token to check.
+         * @return True if the setting exists, false otherwise.
+         */
         bool has_setting(NS_YYCC_BINSTORE_TYPES::Token token) const;
+        /**
+         * @brief Get a setting by its token.
+         * @param[in] token The token of the setting to get.
+         * @return A const reference to the setting.
+         * @exception May throw if the token is invalid.
+         */
         const Setting& get_setting(NS_YYCC_BINSTORE_TYPES::Token token) const;
+        /**
+         * @brief Get all registered settings.
+         * @return A const reference to the vector of registered settings.
+         */
         const std::vector<RegisteredSetting>& all_settings() const;
+        /**
+         * @brief Get the number of settings in the collection.
+         * @return The number of settings.
+         */
         size_t length() const;
+        /**
+         * @brief Check if the collection is empty.
+         * @return True if empty, false otherwise.
+         */
         bool empty() const;
 
     private:
@@ -59,6 +123,6 @@ namespace yycc::carton::binstore::setting {
         std::vector<RegisteredSetting> settings;
     };
 
-}
+} // namespace yycc::carton::binstore::setting
 
 #undef NS_YYCC_BINSTORE_TYPES

src/yycc/carton/binstore/storage.hpp

@@ -1,3 +1,7 @@
+/**
+ * @file storage.hpp
+ * @brief Storage management for the binstore module.
+ */
 #pragma once
 #include "../../macro/class_copy_move.hpp"
 #include "types.hpp"
@@ -45,6 +49,7 @@ namespace yycc::carton::binstore::storage {
         AcceptAll,
     };
 
+    /// @brief Main storage class for managing binary settings storage.
     class Storage {
     private:
         /**
@@ -56,15 +61,46 @@ namespace yycc::carton::binstore::storage {
         NS_YYCC_BINSTORE_CFG::Configuration cfg; ///< The configuration associated with this storage.
 
     public:
+        /**
+         * @brief Construct a new Storage object.
+         * @param[in] cfg The configuration to associate with this storage.
+         */
         Storage(NS_YYCC_BINSTORE_CFG::Configuration&& cfg);
         ~Storage();
         YYCC_DEFAULT_COPY_MOVE(Storage)
 
     public:
-        NS_YYCC_BINSTORE_TYPES::BinstoreResult<void> load_from_file(const std::filesystem::path& fpath, LoadStrategy strategy = LoadStrategy::MigrateOld);
+        /**
+         * @brief Load settings from a file.
+         * @param[in] fpath Path to the file to load from.
+         * @param[in] strategy The load strategy to use. Defaults to MigrateOld.
+         * @return A BinstoreResult indicating success or failure.
+         */
+        NS_YYCC_BINSTORE_TYPES::BinstoreResult<void> load_from_file(const std::filesystem::path& fpath,
+                                                                    LoadStrategy strategy = LoadStrategy::MigrateOld);
+
+        /**
+         * @brief Load settings from an input stream.
+         * @param[in] s The input stream to load from.
+         * @param[in] strategy The load strategy to use. Defaults to MigrateOld.
+         * @return A BinstoreResult indicating success or failure.
+         */
         NS_YYCC_BINSTORE_TYPES::BinstoreResult<void> load(std::istream& s, LoadStrategy strategy = LoadStrategy::MigrateOld);
+
+        /**
+         * @brief Save settings to a file.
+         * @param[in] fpath Path to the file to save to.
+         * @return A BinstoreResult indicating success or failure.
+         */
         NS_YYCC_BINSTORE_TYPES::BinstoreResult<void> save_into_file(const std::filesystem::path& fpath);
+
+        /**
+         * @brief Save settings to an output stream.
+         * @param[in] s The output stream to save to.
+         * @return A BinstoreResult indicating success or failure.
+         */
         NS_YYCC_BINSTORE_TYPES::BinstoreResult<void> save(std::ostream& s);
+
         /**
          * @brief Clear all raw data saved in internal cache.
          * @details This will cause every setting was set in default value when user fetching them.

src/yycc/carton/clap.hpp

@@ -10,5 +10,21 @@
 #include "clap/resolver.hpp"
 
 // TODO: Support multiple arguments for single option.
-
+/**
+ * @brief Command Line Argument Parser (CLAP) module for handling command line arguments and environment variables.
+ * @details This module provides a comprehensive system for defining, parsing, and validating command line
+ * arguments and environment variables. It includes components for defining application metadata,
+ * command line options, variables, and utilities for parsing and validation.
+ * 
+ * The main components include:
+ * \li Types: Error types and result types used throughout the module
+ * \li Validator: Type-safe validation for command line argument values
+ * \li Option: Command line options with short and long names
+ * \li Variable: Environment variables that can be captured
+ * \li Summary: Application metadata (name, version, author, description)
+ * \li Application: Complete application definition with options and variables
+ * \li Manual: Help and version information generation
+ * \li Parser: Command line argument parsing functionality
+ * \li Resolver: Environment variable resolution functionality
+ */
 namespace yycc::carton::clap {}