From a876525e75fc468dc0686d2ad1f403359d625da7 Mon Sep 17 00:00:00 2001
From: Bugen Zhao <i@bugenzhao.com>
Date: Thu, 17 Oct 2024 18:09:01 +0800
Subject: [PATCH] add some docs

Signed-off-by: Bugen Zhao <i@bugenzhao.com>
---
 src/common/src/hash/consistent_hash/compat.rs | 38 +++++++++++--------
 1 file changed, 23 insertions(+), 15 deletions(-)

diff --git a/src/common/src/hash/consistent_hash/compat.rs b/src/common/src/hash/consistent_hash/compat.rs
index ab061a584ad05..6d1a828952783 100644
--- a/src/common/src/hash/consistent_hash/compat.rs
+++ b/src/common/src/hash/consistent_hash/compat.rs
@@ -16,15 +16,20 @@ use std::num::NonZeroUsize;
 
 use super::vnode::VirtualNode;
 
+/// The different cases of `maybe_vnode_count` field in the protobuf message.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
 pub enum VnodeCount {
+    /// The field is a placeholder and has to be filled first before using it.
     #[default]
     Placeholder,
+    /// The field is set to a specific value.
     Set(NonZeroUsize),
+    /// The field is unset because it's persisted in an older version.
     Compat,
 }
 
 impl VnodeCount {
+    /// Creates a `VnodeCount` set to the given value.
     pub fn set(v: impl TryInto<NonZeroUsize>) -> Self {
         VnodeCount::Set(
             v.try_into()
@@ -32,18 +37,7 @@ impl VnodeCount {
         )
     }
 
-    pub fn for_test() -> Self {
-        Self::set(VirtualNode::COUNT_FOR_TEST)
-    }
-
-    pub fn from_protobuf(v: Option<u32>) -> Self {
-        match v {
-            None => VnodeCount::Compat,
-            Some(0) => VnodeCount::Placeholder,
-            Some(v) => VnodeCount::set(v as usize),
-        }
-    }
-
+    /// Converts to protobuf representation for `maybe_vnode_count`.
     pub fn to_protobuf(self) -> Option<u32> {
         match self {
             VnodeCount::Placeholder => Some(0),
@@ -52,10 +46,16 @@ impl VnodeCount {
         }
     }
 
-    pub fn value(self) -> usize {
-        self.value_opt().expect("vnode count not set")
+    /// Converts from protobuf representation of `maybe_vnode_count`.
+    pub fn from_protobuf(v: Option<u32>) -> Self {
+        match v {
+            None => VnodeCount::Compat,
+            Some(0) => VnodeCount::Placeholder,
+            Some(v) => VnodeCount::set(v as usize),
+        }
     }
 
+    /// Returns the value of the vnode count, or `None` if it's a placeholder.
     pub fn value_opt(self) -> Option<usize> {
         match self {
             VnodeCount::Placeholder => None,
@@ -63,14 +63,22 @@ impl VnodeCount {
             VnodeCount::Compat => Some(VirtualNode::COUNT_FOR_COMPAT),
         }
     }
+
+    /// Returns the value of the vnode count. Panics if it's a placeholder.
+    pub fn value(self) -> usize {
+        self.value_opt().expect("vnode count not set")
+    }
 }
 
 /// A trait for accessing the vnode count field with backward compatibility.
 pub trait VnodeCountCompat {
+    /// Get the `maybe_vnode_count` field.
     fn vnode_count_inner(&self) -> VnodeCount;
 
     /// Returns the vnode count, or [`VirtualNode::COUNT_FOR_COMPAT`] if the vnode count is not set,
-    /// typically for backward compatibility.
+    /// typically for backward compatibility. Panics if the field is a placeholder.
+    ///
+    /// Equivalent to `self.vnode_count_inner().value()`.
     ///
     /// See the documentation on the field of the implementing type for more details.
     fn vnode_count(&self) -> usize {