doc: transaction client

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

src/kv/codec.rs

@@ -16,7 +16,7 @@ pub fn max_encoded_bytes_size(n: usize) -> usize {
 }
 
 pub trait BytesEncoder: Write {
-    /// Refer: https://github.com/facebook/mysql-5.6/wiki/MyRocks-record-format#memcomparable-format
+    /// Refer: <https://github.com/facebook/mysql-5.6/wiki/MyRocks-record-format#memcomparable-format>
     ///
     /// Duplicate from components/tikv_util/src/codec/bytes.rs.
     fn encode_bytes(&mut self, key: &[u8], desc: bool) -> Result<()> {

src/raw/client.rs

@@ -26,7 +26,7 @@ pub struct Client {
 }
 
 impl Client {
-    /// Create a new [`Client`](Client).
+    /// Create a new raw [`Client`](Client).
     ///
     /// ```rust,no_run
     /// # use tikv_client::{Config, RawClient};

src/transaction/client.rs

@@ -15,7 +15,23 @@ use tikv_client_proto::{kvrpcpb, pdpb::Timestamp};
 
 const SCAN_LOCK_BATCH_SIZE: u32 = 1024; // TODO: cargo-culted value
 
-/// The TiKV transactional `Client` is used to issue requests to the TiKV server and PD cluster.
+/// The TiKV transactional `Client` is used to interact with TiKV using transactional (MVCC) requests.
+///
+/// A [`Transaction`](crate::transaction::Transaction) provides a SQL-like interface. 
+/// It begins with a [`begin`](Client::begin) or [`begin_pessimistic`](Client::begin_pessimistic) request
+/// and ends with a `rollback` or `commit` request.
+/// If a `Transaction` is dropped before it's rolled back or committed, it is automatically rolled back.
+///
+/// Transaction supports optimistic and pessimistic modes, for mroe deatils, check our 
+/// [SIG-transaction](https://github.com/tikv/sig-transaction/tree/master/doc/tikv#optimistic-and-pessimistic-transactions).
+///
+/// Besides transaction, the client provides some utility methods:
+/// - `gc`: execute a GC process which clear stale data. It is not stablized yet.
+/// - `current_timestamp`: get the current `Timestamp`.
+/// - `snapshot`: get the [`Snapshot`](crate::transaction::Snapshot) of the database at a certain timestamp.
+/// A `Snapshot` is a read-only transaction.
+///
+/// The returned results of transactional requests are [`Future`](std::future::Future)s that must be awaited to execute.
 pub struct Client {
     pd: Arc<PdRpcClient>,
     /// The thread pool for background tasks including committing secondary keys and failed
@@ -25,7 +41,7 @@ pub struct Client {
 }
 
 impl Client {
-    /// Creates a new [`Client`](Client) once the [`Connect`](Connect) resolves.
+    /// Creates a transactional [`Client`](Client).
     ///
     /// ```rust,no_run
     /// use tikv_client::{Config, TransactionClient};
@@ -36,8 +52,6 @@ impl Client {
     /// ```
     pub async fn new(config: Config) -> Result<Client> {
         let bg_worker = ThreadPool::new()?;
-        // TODO: PdRpcClient::connect currently uses a blocking implementation.
-        //       Make it asynchronous later.
         let pd = Arc::new(PdRpcClient::connect(&config, true).await?);
         Ok(Client {
             pd,
@@ -54,9 +68,13 @@ impl Client {
         }
     }
 
-    /// Creates a new [`Transaction`](Transaction).
+    /// Creates a new [`Transaction`](Transaction) in optimistic mode.
     ///
-    /// Using the transaction you can issue commands like [`get`](Transaction::get) or [`set`](Transaction::set).
+    /// Using the transaction you can issue commands like [`get`](Transaction::get) or [`put`](Transaction::put).
+    /// 
+    /// Write operations do not lock data in TiKV, thus commit request may fail due to write conflict.
+    ///
+    /// For details, check our [SIG-transaction](https://github.com/tikv/sig-transaction/tree/master/doc/tikv#optimistic-and-pessimistic-transactions).
     ///
     /// ```rust,no_run
     /// use tikv_client::{Config, TransactionClient};
@@ -74,12 +92,28 @@ impl Client {
         Ok(self.new_transaction(timestamp, false))
     }
 
+    /// Creates a new [`Transaction`](Transaction) in pessimistic mode.
+    ///
+    /// Write operations will lock the data until commit, thus commit requests should not suffer from write conflict.
+    /// For details, check our [SIG-transaction](https://github.com/tikv/sig-transaction/tree/master/doc/tikv#optimistic-and-pessimistic-transactions).
+    ///
+    /// ```rust,no_run
+    /// use tikv_client::{Config, TransactionClient};
+    /// use futures::prelude::*;
+    /// # futures::executor::block_on(async {
+    /// let client = TransactionClient::new(Config::default()).await.unwrap();
+    /// let mut transaction = client.begin_pessimistic().await.unwrap();
+    /// // ... Issue some commands.
+    /// let commit = transaction.commit();
+    /// let result: () = commit.await.unwrap();
+    /// # });
+    /// ```
     pub async fn begin_pessimistic(&self) -> Result<Transaction> {
         let timestamp = self.current_timestamp().await?;
         Ok(self.new_transaction(timestamp, true))
     }
 
-    /// Creates a new [`Snapshot`](Snapshot) at the given time.
+    /// Creates a new [`Snapshot`](Snapshot) at the given [`Timestamp`](Timestamp).
     pub fn snapshot(&self, timestamp: Timestamp) -> Snapshot {
         Snapshot::new(self.new_transaction(timestamp, false))
     }
@@ -98,10 +132,12 @@ impl Client {
         self.pd.clone().get_timestamp().await
     }
 
-    /// Cleans stale MVCC records in TiKV.
+    /// Cleans MVCC records whose timestamp is lower than the given `timestamp` in TiKV. 
+    ///
+    /// For each key, the last mutation record (unless it's a deletion) before `safepoint` is retained.
     ///
     /// It is done by:
-    /// 1. resolve all locks with ts <= safepoint
+    /// 1. resolve all locks with ts <= `safepoint`
     /// 2. update safepoint to PD
     ///
     /// This is a simplified version of [GC in TiDB](https://docs.pingcap.com/tidb/stable/garbage-collection-overview).

src/transaction/mod.rs

@@ -2,7 +2,7 @@
 
 //! Transactional related functionality.
 //!
-//! Using the [`TransactionClient`](TransactionClient) you can utilize TiKV's transactional interface.
+//! Using the [`TransactionClient`](client::Client) you can utilize TiKV's transactional interface.
 //!
 //! This interface offers SQL-like transactions on top of the raw interface.
 //!

src/transaction/snapshot.rs

@@ -7,7 +7,7 @@ use std::ops::RangeBounds;
 
 /// A readonly transaction which can have a custom timestamp.
 ///
-/// See the [Transaction](transaction) docs for more information on the methods.
+/// See the [Transaction](struct@crate::Transaction) docs for more information on the methods.
 #[derive(new)]
 pub struct Snapshot {
     transaction: Transaction,