add doxygen

Author: GaspardKirira

include/vix/db/Database.hpp

@@ -3,8 +3,10 @@
  *  @file Database.hpp
  *  @author Gaspard Kirira
  *
- *  Copyright 2025, Gaspard Kirira.  All rights reserved.
+ *  Copyright 2025, Gaspard Kirira.
+ *  All rights reserved.
  *  https://github.com/vixcpp/vix
+ *
  *  Use of this source code is governed by a MIT license
  *  that can be found in the License file.
  *
@@ -23,51 +25,136 @@ namespace vix::config
 
 namespace vix::db
 {
+  /**
+   * @brief Supported database engines.
+   */
   enum class Engine
   {
+    /// MySQL-compatible database engine
     MySQL,
+
+    /// SQLite embedded database engine
     SQLite
   };
 
+  /**
+   * @brief Configuration parameters for a MySQL database.
+   */
   struct MySQLConfig
   {
+    /// Database host
     std::string host;
+
+    /// Username
     std::string user;
+
+    /// Password
     std::string password;
+
+    /// Database name
     std::string database;
+
+    /// Connection pool configuration
     PoolConfig pool{};
   };
 
+  /**
+   * @brief Configuration parameters for a SQLite database.
+   */
   struct SQLiteConfig
   {
+    /// Path to the SQLite database file
     std::string path;
+
+    /// Connection pool configuration
     PoolConfig pool{};
   };
 
+  /**
+   * @brief Unified database configuration.
+   *
+   * Holds engine-specific configuration while exposing a single
+   * entry point for database initialization.
+   */
   struct DbConfig
   {
+    /// Selected database engine
     Engine engine{Engine::MySQL};
+
+    /// MySQL-specific configuration
     MySQLConfig mysql{};
+
+    /// SQLite-specific configuration
     SQLiteConfig sqlite{};
   };
 
+  /**
+   * @brief Build a database configuration from a Vix configuration.
+   *
+   * Extracts database-related settings from a vix::config::Config
+   * instance and maps them to a DbConfig structure.
+   *
+   * @param cfg Vix configuration object.
+   * @return Parsed database configuration.
+   */
   DbConfig make_db_config_from_vix_config(const vix::config::Config &cfg);
 
+  /**
+   * @brief High-level database facade.
+   *
+   * Database owns the connection pool and exposes access to it,
+   * providing a unified entry point for database access within
+   * the application.
+   *
+   * Engine selection and driver wiring are performed at construction
+   * time based on the provided DbConfig.
+   */
   class Database
   {
   public:
+    /**
+     * @brief Construct a database instance.
+     *
+     * Initializes the underlying connection pool according to
+     * the selected engine and configuration.
+     *
+     * @param cfg Database configuration.
+     */
     explicit Database(const DbConfig &cfg);
 
+    /**
+     * @brief Return the selected database engine.
+     *
+     * @return Database engine.
+     */
     Engine engine() const noexcept { return cfg_.engine; }
+
+    /**
+     * @brief Access the database configuration.
+     *
+     * @return Database configuration.
+     */
     const DbConfig &config() const noexcept { return cfg_; }
 
+    /**
+     * @brief Access the connection pool.
+     *
+     * @return Reference to the connection pool.
+     */
     ConnectionPool &pool() noexcept { return pool_; }
+
+    /**
+     * @brief Access the connection pool (const).
+     *
+     * @return Const reference to the connection pool.
+     */
     const ConnectionPool &pool() const noexcept { return pool_; }
 
   private:
     DbConfig cfg_;
     ConnectionPool pool_;
   };
+
 } // namespace vix::db
 
-#endif
+#endif // VIX_DB_DATABASE_HPP

include/vix/db/Sha256.hpp

@@ -3,8 +3,10 @@
  *  @file Sha256.hpp
  *  @author Gaspard Kirira
  *
- *  Copyright 2025, Gaspard Kirira.  All rights reserved.
+ *  Copyright 2025, Gaspard Kirira.
+ *  All rights reserved.
  *  https://github.com/vixcpp/vix
+ *
  *  Use of this source code is governed by a MIT license
  *  that can be found in the License file.
  *
@@ -20,33 +22,103 @@
 
 namespace vix::db
 {
+  /**
+   * @brief Incremental SHA-256 hash calculator.
+   *
+   * Sha256 provides a minimal, self-contained implementation of the
+   * SHA-256 hashing algorithm. It supports incremental updates and
+   * produces a 256-bit digest.
+   *
+   * This utility is primarily intended for internal database-related
+   * features such as migration checksums.
+   */
   class Sha256
   {
   public:
+    /**
+     * @brief Construct a new SHA-256 hasher.
+     *
+     * The hasher is initialized in a reset state.
+     */
     Sha256() { reset(); }
 
+    /**
+     * @brief Reset the internal state.
+     *
+     * After calling reset(), the hasher can be reused to compute
+     * a new digest.
+     */
     void reset();
+
+    /**
+     * @brief Update the hash with raw binary data.
+     *
+     * @param data Pointer to the input buffer.
+     * @param len  Number of bytes to process.
+     */
     void update(const void *data, std::size_t len);
+
+    /**
+     * @brief Update the hash with string data.
+     *
+     * @param s Input string view.
+     */
     void update(std::string_view s) { update(s.data(), s.size()); }
 
+    /**
+     * @brief Finalize the hash and return the digest.
+     *
+     * Calling this function finalizes the computation and returns
+     * the 32-byte SHA-256 digest.
+     *
+     * @return SHA-256 digest.
+     */
     std::array<std::uint8_t, 32> digest();
+
+    /**
+     * @brief Convert a SHA-256 digest to a hexadecimal string.
+     *
+     * @param d Digest bytes.
+     * @return Lowercase hexadecimal representation.
+     */
     static std::string hex(std::array<std::uint8_t, 32> d);
 
   private:
+    /**
+     * @brief Process a single 512-bit message block.
+     *
+     * @param block Input block.
+     */
     void transform(const std::uint8_t block[64]);
 
+    /// Total number of processed bits
     std::uint64_t bitlen_ = 0;
+
+    /// Internal hash state
     std::array<std::uint32_t, 8> state_{};
+
+    /// Partial message buffer
     std::array<std::uint8_t, 64> buffer_{};
+
+    /// Number of bytes currently stored in the buffer
     std::size_t buffer_len_ = 0;
   };
 
+  /**
+   * @brief Compute a SHA-256 hash and return it as hexadecimal.
+   *
+   * Convenience helper for hashing a single string.
+   *
+   * @param s Input string.
+   * @return SHA-256 digest encoded as hexadecimal.
+   */
   inline std::string sha256_hex(std::string_view s)
   {
     Sha256 h;
     h.update(s);
     return Sha256::hex(h.digest());
   }
-}
 
-#endif
+} // namespace vix::db
+
+#endif // VIX_DB_SHA256_HPP

include/vix/db/Transaction.hpp

@@ -3,8 +3,10 @@
  *  @file Transaction.hpp
  *  @author Gaspard Kirira
  *
- *  Copyright 2025, Gaspard Kirira.  All rights reserved.
+ *  Copyright 2025, Gaspard Kirira.
+ *  All rights reserved.
  *  https://github.com/vixcpp/vix
+ *
  *  Use of this source code is governed by a MIT license
  *  that can be found in the License file.
  *
@@ -17,18 +19,40 @@
 
 namespace vix::db
 {
+  /**
+   * @brief RAII wrapper for database transactions.
+   *
+   * Transaction acquires a connection from a ConnectionPool and
+   * starts a database transaction on construction. If the transaction
+   * is still active when the object is destroyed, it is automatically
+   * rolled back.
+   *
+   * This ensures strong exception safety and prevents leaked
+   * transactions.
+   */
   class Transaction
   {
     PooledConn pooled_;
     bool active_ = true;
 
   public:
+    /**
+     * @brief Begin a new transaction using a pooled connection.
+     *
+     * @param pool Connection pool from which to acquire a connection.
+     */
     explicit Transaction(ConnectionPool &pool)
         : pooled_(pool)
     {
       pooled_.get().begin();
     }
 
+    /**
+     * @brief Roll back the transaction if still active.
+     *
+     * The destructor never throws. Any exception raised during rollback
+     * is swallowed to preserve stack unwinding.
+     */
     ~Transaction() noexcept
     {
       if (!active_)
@@ -45,6 +69,14 @@ namespace vix::db
     Transaction(const Transaction &) = delete;
     Transaction &operator=(const Transaction &) = delete;
 
+    /**
+     * @brief Move-construct a transaction.
+     *
+     * Ownership of the active transaction is transferred to the
+     * new instance. The source transaction becomes inactive.
+     *
+     * @param other Transaction to move from.
+     */
     Transaction(Transaction &&other) noexcept
         : pooled_(std::move(other.pooled_)), active_(other.active_)
     {
@@ -53,18 +85,34 @@ namespace vix::db
 
     Transaction &operator=(Transaction &&) = delete;
 
+    /**
+     * @brief Commit the transaction.
+     *
+     * After commit(), the transaction becomes inactive and will
+     * not be rolled back on destruction.
+     */
     void commit()
     {
       pooled_.get().commit();
       active_ = false;
     }
 
+    /**
+     * @brief Roll back the transaction explicitly.
+     *
+     * After rollback(), the transaction becomes inactive.
+     */
     void rollback()
     {
       pooled_.get().rollback();
       active_ = false;
     }
 
+    /**
+     * @brief Access the underlying database connection.
+     *
+     * @return Reference to the active connection.
+     */
     Connection &conn() { return pooled_.get(); }
   };