From b0edd3b71678bbcc03e38c1c260ffff6a0ca2cac Mon Sep 17 00:00:00 2001
From: Jussi Saurio <jussi.saurio@gmail.com>
Date: Thu, 24 Jul 2025 18:36:07 +0300
Subject: [PATCH] btree: WriteState: add comments

---
 core/storage/btree.rs | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/core/storage/btree.rs b/core/storage/btree.rs
index 645d56737..6f1e1eba5 100644
--- a/core/storage/btree.rs
+++ b/core/storage/btree.rs
@@ -228,7 +228,9 @@ struct DeleteInfo {
 
 #[derive(Debug, Clone)]
 pub enum OverwriteCellState {
+    /// Fill the cell payload with the new value.
     FillPayload,
+    /// Clear the overflow pages of the old celland overwrite the cell.
     ClearOverflowPagesAndOverwrite {
         new_payload: Vec<u8>,
         old_offset: usize,
@@ -241,15 +243,21 @@ pub enum OverwriteCellState {
 #[derive(Debug, Clone)]
 enum WriteState {
     Start,
+    /// Overwrite an existing cell.
+    /// In addition to deleting the old cell and writing a new one,
+    /// we may also need to clear the old cell's overflow pages
+    /// and add them to the freelist.
     Overwrite {
         page: Arc<BTreePageInner>,
         cell_idx: usize,
         state: OverwriteCellState,
     },
+    /// Insert a new cell. This path is taken when inserting a new row.
     Insert {
         page: Arc<BTreePageInner>,
         cell_idx: usize,
     },
+    /// Check whether the page overflows and needs balancing after an insert.
     CheckNeedsBalancing {
         page: Arc<BTreePageInner>,
     },