Update documentation

src/commit_request.hpp

@@ -7,26 +7,50 @@
 #include <vector>
 
 /**
- * @brief Represents a precondition for a commit request.
+ * @brief Represents a precondition for optimistic concurrency control.
+ *
+ * Preconditions allow transactions to verify that the data they read
+ * during transaction preparation is still valid at commit time. This
+ * enables optimistic concurrency control by detecting conflicting
+ * modifications from other transactions.
  */
 struct Precondition {
-  enum class Type { PointRead, RangeRead };
+  /**
+   * @brief Type of precondition check to perform.
+   */
+  enum class Type {
+    PointRead, ///< Check existence/content of a single key
+    RangeRead  ///< Check consistency of a key range
+  };
 
-  Type type;
-  uint64_t version;
-  std::string_view begin;
-  std::string_view end;
+  Type type; ///< Type of precondition check
+  uint64_t
+      version; ///< Expected version number (0 uses read_version from request)
+  std::string_view begin; ///< Begin key (or single key for PointRead)
+  std::string_view end;   ///< End key for RangeRead (unused for PointRead)
 };
 
 /**
- * @brief Represents an operation in a commit request.
+ * @brief Represents a mutation operation in a commit request.
+ *
+ * Operations define the actual changes to be applied to the database
+ * if all preconditions pass. Operations are applied in the order they
+ * appear in the commit request.
  */
 struct Operation {
-  enum class Type { Write, Delete, RangeDelete };
+  /**
+   * @brief Type of mutation operation to perform.
+   */
+  enum class Type {
+    Write,      ///< Set a key-value pair
+    Delete,     ///< Remove a single key
+    RangeDelete ///< Remove all keys in a range
+  };
 
-  Type type;
-  std::string_view param1;
-  std::string_view param2;
+  Type type;               ///< Type of operation
+  std::string_view param1; ///< Key for Write/Delete, begin key for RangeDelete
+  std::string_view
+      param2; ///< Value for Write, end key for RangeDelete (unused for Delete)
 };
 
 /**
@@ -147,16 +171,39 @@ public:
 
   // Builder methods for setting data
   // Note: All string_view parameters must point to arena-allocated memory
+
+  /**
+   * @brief Set the optional request ID for this commit.
+   * @param arena_allocated_request_id String view pointing to arena-allocated
+   * memory
+   */
   void set_request_id(std::string_view arena_allocated_request_id) {
     request_id_ = arena_allocated_request_id;
   }
 
+  /**
+   * @brief Set the leader ID for consistency checks.
+   * @param arena_allocated_leader_id String view pointing to arena-allocated
+   * memory
+   */
   void set_leader_id(std::string_view arena_allocated_leader_id) {
     leader_id_ = arena_allocated_leader_id;
   }
 
+  /**
+   * @brief Set the read version for precondition validation.
+   * @param read_version The snapshot version number
+   */
   void set_read_version(uint64_t read_version) { read_version_ = read_version; }
 
+  /**
+   * @brief Add a precondition to the commit request.
+   * @param type Type of precondition (PointRead or RangeRead)
+   * @param version Version number for the precondition check
+   * @param arena_allocated_begin Begin key (or single key for PointRead)
+   * @param arena_allocated_end End key for RangeRead (optional, empty for
+   * PointRead)
+   */
   void add_precondition(Precondition::Type type, uint64_t version,
                         std::string_view arena_allocated_begin,
                         std::string_view arena_allocated_end = {}) {
@@ -164,6 +211,14 @@ public:
                                           arena_allocated_end});
   }
 
+  /**
+   * @brief Add an operation to the commit request.
+   * @param type Type of operation (Write, Delete, or RangeDelete)
+   * @param arena_allocated_param1 Key for Write/Delete, begin key for
+   * RangeDelete
+   * @param arena_allocated_param2 Value for Write, end key for RangeDelete
+   * (optional for Delete)
+   */
   void add_operation(Operation::Type type,
                      std::string_view arena_allocated_param1,
                      std::string_view arena_allocated_param2 = {}) {