docs: update docs of lease client

Signed-off-by: bsbds <[email protected]>
xline-kv · Jul 28, 2023 · 7ed94f5 · 7ed94f5
1 parent d3adac9
commit 7ed94f5
Show file tree

Hide file tree

Showing 2 changed files with 29 additions and 18 deletions.
diff --git a/xline-client/src/clients/lease.rs b/xline-client/src/clients/lease.rs
@@ -23,7 +23,7 @@ use crate::{
 /// Client for Lease operations.
 #[derive(Clone, Debug)]
 pub struct LeaseClient {
-    /// Name of the LeaseClient
+    /// Name of the LeaseClient, which will be used in CURP propose id generation
     name: String,
     /// The client running the CURP protocol, communicate with all servers.
     curp_client: Arc<CurpClient<Command>>,
@@ -36,7 +36,7 @@ pub struct LeaseClient {
 }
 
 impl LeaseClient {
-    /// New `LeaseClient`
+    /// Creates a new `LeaseClient`
     #[inline]
     pub fn new(
         name: String,
@@ -57,11 +57,13 @@ impl LeaseClient {
         }
     }
 
-    /// Send `LeaseGrantRequest` by `CurpClient`
+    /// Creates a lease which expires if the server does not receive a keepAlive
+    /// within a given time to live period. All keys attached to the lease will be expired and
+    /// deleted if the lease expires. Each expired key generates a delete event in the event history.
     ///
     /// # Errors
     ///
-    /// If `CurpClient` failed to send request
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn grant(&mut self, mut request: LeaseGrantRequest) -> Result<LeaseGrantResponse> {
         let propose_id = self.generate_propose_id();
@@ -77,22 +79,23 @@ impl LeaseClient {
         Ok(cmd_res.decode().into())
     }
 
-    /// Send `LeaseRevokeRequest` by `CurpClient`
+    /// Revokes a lease. All keys attached to the lease will expire and be deleted.
     ///
     /// # Errors
     ///
-    /// If client failed to send request
+    /// This function will return an error if the inner RPC client encountered a propose failure
     #[inline]
     pub async fn revoke(&mut self, request: LeaseRevokeRequest) -> Result<LeaseRevokeResponse> {
         let res = self.lease_client.lease_revoke(request.inner).await?;
         Ok(res.into_inner())
     }
 
-    /// Send `LeaseKeepAliveRequest` by `CurpClient`
+    /// Keeps the lease alive by streaming keep alive requests from the client
+    /// to the server and streaming keep alive responses from the server to the client.
     ///
     /// # Errors
     ///
-    /// If client failed to send request
+    /// This function will return an error if the inner RPC client encountered a propose failure
     #[inline]
     pub async fn keep_alive(
         &mut self,
@@ -122,11 +125,11 @@ impl LeaseClient {
         Ok((LeaseKeeper::new(id, sender), stream))
     }
 
-    /// Send `LeaseTimeToLiveRequest` by `CurpClient`
+    /// Retrieves lease information.
     ///
     /// # Errors
     ///
-    /// If client failed to send request
+    /// This function will return an error if the inner RPC client encountered a propose failure
     #[inline]
     pub async fn time_to_live(
         &mut self,
@@ -143,7 +146,7 @@ impl LeaseClient {
     ///
     /// # Errors
     ///
-    /// If client failed to send request
+    /// This function will return an error if the inner CURP client encountered a propose failure
     #[inline]
     pub async fn leases(&mut self) -> Result<LeaseLeasesResponse> {
         let propose_id = self.generate_propose_id();

diff --git a/xline-client/src/types/lease.rs b/xline-client/src/types/lease.rs
@@ -29,7 +29,7 @@ impl LeaseKeeper {
     ///
     /// # Errors
     ///
-    /// If the sender fails to send
+    /// This function will return an error if the inner channel is closed
     #[inline]
     pub fn keep_alive(&mut self) -> Result<()> {
         self.sender
@@ -46,7 +46,9 @@ pub struct LeaseGrantRequest {
 }
 
 impl LeaseGrantRequest {
-    /// New `LeaseGrantRequest`
+    /// Creates a new `LeaseGrantRequest`
+    ///
+    /// `ttl` is the advisory time-to-live in seconds. Expired lease will return -1.
     #[inline]
     #[must_use]
     pub fn new(ttl: i64) -> Self {
@@ -58,7 +60,7 @@ impl LeaseGrantRequest {
         }
     }
 
-    /// Set `id`
+    /// `id` is the requested ID for the lease. If ID is set to 0, the lessor chooses an ID.
     #[inline]
     #[must_use]
     pub fn with_id(mut self, id: i64) -> Self {
@@ -82,7 +84,9 @@ pub struct LeaseRevokeRequest {
 }
 
 impl LeaseRevokeRequest {
-    /// New `LeaseRevokeRequest`
+    /// Creates a new `LeaseRevokeRequest`
+    ///
+    /// `id` is the lease ID to revoke. When the ID is revoked, all associated keys will be deleted.
     #[inline]
     #[must_use]
     pub fn new(id: i64) -> Self {
@@ -107,7 +111,9 @@ pub struct LeaseKeepAliveRequest {
 }
 
 impl LeaseKeepAliveRequest {
-    /// New `LeaseKeepAliveRequest`
+    /// Creates a new `LeaseKeepAliveRequest`
+    ///
+    /// `id` is the lease ID for the lease to keep alive.
     #[inline]
     #[must_use]
     pub fn new(id: i64) -> Self {
@@ -132,7 +138,9 @@ pub struct LeaseTimeToLiveRequest {
 }
 
 impl LeaseTimeToLiveRequest {
-    /// New `LeaseTimeToLiveRequest`
+    /// Creates a new `LeaseTimeToLiveRequest`
+    ///
+    /// `id` is the lease ID for the lease.
     #[inline]
     #[must_use]
     pub fn new(id: i64) -> Self {
@@ -144,7 +152,7 @@ impl LeaseTimeToLiveRequest {
         }
     }
 
-    /// Set `keys`
+    /// `keys` is true to query all the keys attached to this lease.
     #[inline]
     #[must_use]
     pub fn with_keys(mut self, keys: bool) -> Self {