docs: add doc comments, fix visibility, and polish API (#11)

- Add doc comments to all public option enums, result types, and
  notification types with descriptions of each variant
- Add doc comment with code example to OxiaClientBuilder
- Fix DeleteRangeOperation visibility to pub(crate)
- Fix ephemeral example: use separate variable after shutdown
- Total: 48 tests passing (12 unit + 35 integration + 1 doctest)

Signed-off-by: mattisonchao <mattisonchao@gmail.com>

Author: mattisonchao

liboxia-native/examples/metadata_ephemeral.rs

@@ -14,7 +14,7 @@ async fn main() {
         .with_target(false)
         .init();
 
-    let mut client = OxiaClientBuilder::new().build().await.unwrap();
+    let client = OxiaClientBuilder::new().build().await.unwrap();
     let key = String::from("key1");
     let payload = "payload".to_string().into_bytes();
 
@@ -27,13 +27,13 @@ async fn main() {
         "put the ephemeral record. key {:?} value {:?} version {:?}",
         put_result.key, payload, put_result.version
     );
-    // close the client
+    // close the client (this closes the session, which should delete ephemeral records)
     client.shutdown().await.unwrap();
 
-    // create a new client
-    client = OxiaClientBuilder::new().build().await.unwrap();
-    let result = client.get(key.clone()).await;
+    // create a new client and verify the ephemeral record is gone
+    let client2 = OxiaClientBuilder::new().build().await.unwrap();
+    let result = client2.get(key.clone()).await;
     info!("get the value again. error: {:?}", result.unwrap_err());
 
-    client.shutdown().await.unwrap();
+    client2.shutdown().await.unwrap();
 }

liboxia-native/src/client.rs

@@ -28,45 +28,70 @@ use tokio::task::JoinSet;
 use tonic::codegen::tokio_stream::StreamExt;
 use tonic::{async_trait, Request};
 
+/// Options for put operations.
 pub enum PutOption {
-    /// Only succeed if the record does not already exist (equivalent to ExpectVersionId(-1))
+    /// Only succeed if the record does not already exist (equivalent to ExpectVersionId(-1)).
     ExpectedRecordNotExists(),
-    /// Only succeed if the current version matches
+    /// Only succeed if the current version matches the specified version ID (CAS operation).
     ExpectVersionId(i64),
+    /// Override partition routing. Records with the same partition key are co-located on the same shard.
     PartitionKey(String),
+    /// Server-assigned atomic sequential keys. The key will get added suffixes based on
+    /// adding the delta to the current highest key with the same prefix.
     SequenceKeyDelta(Vec<u64>),
+    /// Associate secondary indexes with the record for alternative query paths.
     SecondaryIndexes(Vec<SecondaryIndex>),
+    /// Create an ephemeral record that is automatically deleted when the client's session
+    /// is closed or expires.
     Ephemeral(),
 }
 
+/// The result of a put operation.
 #[derive(Clone, Debug, PartialEq)]
 pub struct PutResult {
+    /// The key of the stored record. May differ from the requested key when using sequence deltas.
     pub key: String,
+    /// The version metadata of the stored record.
     pub version: Version,
 }
 
+/// Options for delete operations.
 pub enum DeleteOption {
+    /// Override partition routing.
     PartitionKey(String),
+    /// Only delete if the current version matches (conditional delete).
     ExpectVersionId(i64),
+    /// Only delete if the record does not exist (no-op check).
     RecordDoesNotExist(),
 }
 
+/// Options for delete range operations.
 pub enum DeleteRangeOption {
+    /// Override partition routing.
     PartitionKey(String),
 }
 
+/// Options for get operations.
 pub enum GetOption {
+    /// Key comparison type: Equal (default), Floor, Ceiling, Lower, Higher.
     ComparisonType(KeyComparisonType),
+    /// Override partition routing.
     PartitionKey(String),
-    /// Include the value in the response (default: true)
+    /// Whether to include the value in the response (default: true).
+    /// Set to false for metadata-only queries.
     IncludeValue(bool),
+    /// Query a secondary index instead of the primary key space.
     UseIndex(String),
 }
 
+/// The result of a get operation.
 #[derive(Clone, Debug, PartialEq)]
 pub struct GetResult {
+    /// The key of the record. May differ from the requested key when using comparison queries.
     pub key: String,
+    /// The value of the record. None if the value was not requested or the record has no value.
     pub value: Option<Vec<u8>>,
+    /// The version metadata of the record.
     pub version: Version,
 }
 impl Eq for GetResult {}
@@ -83,32 +108,47 @@ impl Ord for GetResult {
     }
 }
 
+/// Options for list operations.
 pub enum ListOption {
+    /// Override partition routing.
     PartitionKey(String),
+    /// Query a secondary index instead of the primary key space.
     UseIndex(String),
 }
 
+/// The result of a list operation.
 #[derive(Clone, Debug, PartialEq)]
 pub struct ListResult {
+    /// The keys found within the specified range.
     pub keys: Vec<String>,
 }
 
+/// Options for range scan operations.
 pub enum RangeScanOption {
+    /// Override partition routing.
     PartitionKey(String),
+    /// Query a secondary index instead of the primary key space.
     UseIndex(String),
 }
 
+/// The result of a range scan operation.
 #[derive(Clone, Debug, PartialEq)]
 pub struct RangeScanResult {
+    /// The records found within the specified range, including keys, values, and versions.
     pub records: Vec<GetResult>,
 }
 
+/// Options for notification subscriptions.
 pub enum GetNotificationOption {
+    /// Buffer size for the notification channel (default: 100).
     BufferSize(usize),
 }
 
+/// Options for sequence update subscriptions.
 pub enum GetSequenceUpdatesOption {
+    /// Required: the partition key for the sequence. Must be specified.
     PartitionKey(String),
+    /// Buffer size for the sequence updates channel (default: 100).
     BufferSize(usize),
 }
 
@@ -135,12 +175,18 @@ pub struct KeyRangeDeleted {
     pub key_range_last: Option<String>,
 }
 
+/// A change notification received from Oxia.
 #[derive(Clone, Debug, PartialEq)]
 pub enum Notification {
+    /// A new key was created.
     KeyCreated(KeyCreated),
+    /// A key was deleted.
     KeyDeleted(KeyDeleted),
+    /// An existing key was modified.
     KeyModified(KeyModified),
+    /// A range of keys was deleted.
     KeyRangeDeleted(KeyRangeDeleted),
+    /// An unknown notification type was received.
     Unknown(),
 }
 

liboxia-native/src/client_builder.rs

@@ -4,6 +4,23 @@ use crate::client_options::OxiaClientOptions;
 use crate::errors::OxiaError;
 use std::time::Duration;
 
+/// Builder for creating an [`OxiaClient`] with custom configuration.
+///
+/// # Example
+/// ```no_run
+/// # async fn example() {
+/// use liboxia::client_builder::OxiaClientBuilder;
+/// use std::time::Duration;
+///
+/// let client = OxiaClientBuilder::new()
+///     .service_address("localhost:6648".to_string())
+///     .namespace("my-namespace".to_string())
+///     .session_timeout(Duration::from_secs(30))
+///     .build()
+///     .await
+///     .unwrap();
+/// # }
+/// ```
 #[derive(Debug, Clone, Default)]
 pub struct OxiaClientBuilder {
     service_address: Option<String>,

liboxia-native/src/operations.rs

@@ -170,7 +170,7 @@ impl CompletableOperation<DeleteResponse> for DeleteOperation {
 }
 
 #[derive(Default)]
-pub struct DeleteRangeOperation {
+pub(crate) struct DeleteRangeOperation {
     pub(crate) callback: Option<Sender<Result<DeleteRangeResponse, OxiaError>>>,
     pub(crate) partition_key: Option<String>,
     pub(crate) start_inclusive: String,