add doxygen

GaspardKirira · GaspardKirira · commit 5aab360a9fa2 · 2026-02-03T14:35:28.000+03:00
diff --git a/include/vix/orm/Entity.hpp b/include/vix/orm/Entity.hpp
@@ -3,8 +3,10 @@
  *  @file Entity.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.
  *
@@ -18,10 +20,21 @@
 
 namespace vix::orm
 {
+  /**
+   * @brief Base class for ORM entities.
+   *
+   * Entity is the common base type for all ORM-managed objects.
+   * It provides a polymorphic interface and a virtual destructor,
+   * allowing entities to be handled via base pointers or references.
+   *
+   * This type intentionally contains no data or behavior and serves
+   * purely as a semantic marker and extension point for the ORM.
+   */
   struct Entity
   {
     virtual ~Entity() = default;
   };
-} // namespace Vix::orm
+
+} // namespace vix::orm
 
 #endif // VIX_ENTITY_HPP
diff --git a/include/vix/orm/Mapper.hpp b/include/vix/orm/Mapper.hpp
@@ -3,8 +3,10 @@
  *  @file Mapper.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,23 +25,72 @@
 namespace vix::orm
 {
   /**
-   * User-specialized mapper.
+   * @brief User-specialized mapper for ORM entities.
+   *
+   * Mapper<T> defines how an ORM entity of type @p T is:
+   * - constructed from a database result row
+   * - converted into parameters for INSERT statements
+   * - converted into parameters for UPDATE statements
+   *
+   * This template is intended to be fully specialized by the user
+   * for each entity type.
    *
    * Example:
+   * @code
    * template<>
-   * struct Mapper<User> { ... };
+   * struct Mapper<User>
+   * {
+   *   static User fromRow(const vix::db::ResultRow &row);
+   *
+   *   static std::vector<std::pair<std::string, std::any>>
+   *   toInsertParams(const User &u);
+   *
+   *   static std::vector<std::pair<std::string, std::any>>
+   *   toUpdateParams(const User &u);
+   * };
+   * @endcode
    */
   template <class T>
   struct Mapper
   {
+    /**
+     * @brief Construct an entity instance from a database row.
+     *
+     * This method is called when materializing query results
+     * into ORM entities.
+     *
+     * @param row Database result row.
+     * @return Constructed entity instance.
+     */
     static T fromRow(const vix::db::ResultRow &row);
 
+    /**
+     * @brief Produce parameters for an INSERT statement.
+     *
+     * Returns a list of column/value pairs representing the
+     * fields to be inserted. Values are stored as std::any
+     * and later converted to DbValue by the ORM.
+     *
+     * @param v Entity instance.
+     * @return List of column/value pairs.
+     */
     static std::vector<std::pair<std::string, std::any>>
     toInsertParams(const T &v);
 
+    /**
+     * @brief Produce parameters for an UPDATE statement.
+     *
+     * Returns a list of column/value pairs representing the
+     * fields to be updated. Typically excludes immutable
+     * fields such as primary keys.
+     *
+     * @param v Entity instance.
+     * @return List of column/value pairs.
+     */
     static std::vector<std::pair<std::string, std::any>>
     toUpdateParams(const T &v);
   };
+
 } // namespace vix::orm
 
 #endif // VIX_MAPPER_HPP
diff --git a/include/vix/orm/QueryBuilder.hpp b/include/vix/orm/QueryBuilder.hpp
@@ -3,14 +3,15 @@
  *  @file QueryBuilder.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.
  *
  *  Vix.cpp
  */
-
 #ifndef VIX_QUERY_BUILDER
 #define VIX_QUERY_BUILDER
 
@@ -22,36 +23,77 @@
 
 namespace vix::orm
 {
+  /**
+   * @brief Lightweight SQL query builder with bound parameters.
+   *
+   * QueryBuilder helps construct SQL statements incrementally while
+   * keeping parameters separated from the SQL string. Parameters are
+   * collected as DbValue instances and are intended to be bound to a
+   * prepared statement by the ORM or DB layer.
+   *
+   * This class does not attempt to validate SQL syntax and intentionally
+   * avoids abstraction leakage. It is designed to be minimal, explicit,
+   * and composable.
+   */
   class QueryBuilder
   {
     std::string sql_;
     std::vector<vix::db::DbValue> params_;
 
   public:
+    /**
+     * @brief Append raw SQL text.
+     *
+     * @param s SQL fragment.
+     * @return Reference to this builder.
+     */
     QueryBuilder &raw(std::string_view s)
     {
       sql_.append(s);
       return *this;
     }
 
+    /**
+     * @brief Append a single space character.
+     *
+     * Convenience helper for readable chaining.
+     *
+     * @return Reference to this builder.
+     */
     QueryBuilder &space()
     {
       sql_.push_back(' ');
       return *this;
     }
 
+    /**
+     * @brief Append a parameter value.
+     *
+     * The parameter is stored and expected to be bound to the
+     * next positional placeholder by the caller.
+     *
+     * @param v Database value.
+     * @return Reference to this builder.
+     */
     QueryBuilder &param(const vix::db::DbValue &v)
     {
       params_.push_back(v);
       return *this;
     }
 
+    /**
+     * @brief Append a parameter value (move).
+     *
+     * @param v Database value.
+     * @return Reference to this builder.
+     */
     QueryBuilder &param(vix::db::DbValue &&v)
     {
       params_.push_back(std::move(v));
       return *this;
     }
 
+    /// Convenience overloads for common C++ types
     QueryBuilder &param(std::int64_t v) { return param(vix::db::i64(v)); }
     QueryBuilder &param(int v) { return param(vix::db::i64(static_cast<std::int64_t>(v))); }
     QueryBuilder &param(std::uint64_t v) { return param(vix::db::i64(static_cast<std::int64_t>(v))); }
@@ -61,11 +103,28 @@ namespace vix::orm
     QueryBuilder &param(std::string v) { return param(vix::db::str(std::move(v))); }
     QueryBuilder &param(const char *v) { return param(vix::db::str(std::string(v ? v : ""))); }
 
+    /**
+     * @brief Append a NULL parameter.
+     *
+     * @return Reference to this builder.
+     */
     QueryBuilder &paramNull() { return param(vix::db::null()); }
 
+    /**
+     * @brief Access the constructed SQL string.
+     *
+     * @return SQL string.
+     */
     const std::string &sql() const { return sql_; }
+
+    /**
+     * @brief Access the collected parameters.
+     *
+     * @return Vector of bound parameters.
+     */
     const std::vector<vix::db::DbValue> &params() const { return params_; }
   };
+
 } // namespace vix::orm
 
 #endif // VIX_QUERY_BUILDER
diff --git a/include/vix/orm/Repository.hpp b/include/vix/orm/Repository.hpp
@@ -3,8 +3,10 @@
  *  @file Repository.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.
  *
@@ -25,13 +27,28 @@
 
 namespace vix::orm
 {
+  /**
+   * @brief Generic repository for ORM entities.
+   *
+   * BaseRepository<T> provides a minimal CRUD interface for an
+   * ORM entity mapped to a single database table.
+   *
+   * Assumptions:
+   * - The underlying table uses a primary key column named "id"
+   * - The Mapper<T> specialization defines how the entity is
+   *   serialized/deserialized
+   *
+   * This class intentionally avoids complex query abstraction
+   * and focuses on predictable, explicit SQL.
+   */
   template <class T>
   class BaseRepository
   {
     vix::db::ConnectionPool &pool_;
     std::string table_;
 
-    static std::string build_insert_cols(const std::vector<std::pair<std::string, std::any>> &params)
+    static std::string
+    build_insert_cols(const std::vector<std::pair<std::string, std::any>> &params)
     {
       std::string cols;
       cols.reserve(64);
@@ -59,7 +76,8 @@ namespace vix::orm
       return qs;
     }
 
-    static std::string build_update_set(const std::vector<std::pair<std::string, std::any>> &params)
+    static std::string
+    build_update_set(const std::vector<std::pair<std::string, std::any>> &params)
     {
       std::string set;
       set.reserve(128);
@@ -75,9 +93,23 @@ namespace vix::orm
     }
 
   public:
+    /**
+     * @brief Construct a repository bound to a table.
+     *
+     * @param pool  Connection pool used for queries.
+     * @param table Database table name.
+     */
     BaseRepository(vix::db::ConnectionPool &pool, std::string table)
         : pool_(pool), table_(std::move(table)) {}
 
+    /**
+     * @brief Insert a new entity.
+     *
+     * Uses Mapper<T>::toInsertParams to build the INSERT statement.
+     *
+     * @param v Entity instance.
+     * @return Generated primary key (last insert id).
+     */
     std::uint64_t create(const T &v)
     {
       const auto params = Mapper<T>::toInsertParams(v);
@@ -98,6 +130,12 @@ namespace vix::orm
       return pc.get().lastInsertId();
     }
 
+    /**
+     * @brief Find an entity by its primary key.
+     *
+     * @param id Primary key value.
+     * @return Entity instance if found, otherwise std::nullopt.
+     */
     std::optional<T> findById(std::int64_t id)
     {
       const std::string sql =
@@ -111,10 +149,18 @@ namespace vix::orm
       if (!rs || !rs->next())
         return std::nullopt;
 
-      // Mapper<T>::fromRow expects a ResultRow
       return Mapper<T>::fromRow(rs->row());
     }
 
+    /**
+     * @brief Update an entity by its primary key.
+     *
+     * Uses Mapper<T>::toUpdateParams to generate column assignments.
+     *
+     * @param id Primary key value.
+     * @param v  Entity instance.
+     * @return Number of affected rows.
+     */
     std::uint64_t updateById(std::int64_t id, const T &v)
     {
       const auto params = Mapper<T>::toUpdateParams(v);
@@ -134,6 +180,12 @@ namespace vix::orm
       return st->exec();
     }
 
+    /**
+     * @brief Delete an entity by its primary key.
+     *
+     * @param id Primary key value.
+     * @return Number of affected rows.
+     */
     std::uint64_t removeById(std::int64_t id)
     {
       vix::db::PooledConn pc(pool_);
diff --git a/include/vix/orm/UnitOfWork.hpp b/include/vix/orm/UnitOfWork.hpp
diff --git a/include/vix/orm/db_compat.hpp b/include/vix/orm/db_compat.hpp
