doc: snapshot

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

src/kv/bound_range.rs

@@ -19,7 +19,7 @@ use tikv_client_proto::kvrpcpb;
 /// In TiKV, keys are an ordered sequence of bytes. This means we can have ranges over those
 /// bytes. Eg `001` is before `010`.
 ///
-/// **Minimum key**: there is the minimum key: empty key. So a range may not be unbounded below. 
+/// **Minimum key**: there is the minimum key: empty key. So a range may not be unbounded below.
 /// The unbounded lower bound in a [`Range`](Range) will be converted to an empty key.
 ///
 /// **Maximum key**: There is no limit of the maximum key. When an empty key is used as the upper bound, it means upper unbounded.

src/raw/client.rs

@@ -13,9 +13,9 @@ const MAX_RAW_KV_SCAN_LIMIT: u32 = 10240;
 
 /// The TiKV raw `Client` is used to interact with TiKV using raw requests.
 ///
-/// Raw requests don't need a wrapping transaction. 
+/// Raw requests don't need a wrapping transaction.
 /// Each request is immediately processed once executed.
-/// 
+///
 /// The returned results of raw requests are [`Future`](std::future::Future)s that must be awaited to execute.
 ///
 #[derive(Clone)]
@@ -50,7 +50,7 @@ impl Client {
     /// supplied column family constraint. The original `Client` can still be used.
     ///
     /// By default, raw client uses the `Default` column family.
-    /// 
+    ///
     /// For normal users of the raw API, you don't need to use other column families.
     ///
     /// ```rust,no_run
@@ -75,7 +75,7 @@ impl Client {
     /// This function returns a new `Client`, requests created with it will have the
     /// supplied `key_only` option. The original `Client` can still be used. `key_only`
     /// is only relevant for `scan`-like requests, for other kinds of request, it
-    /// will be ignored. 
+    /// will be ignored.
     /// With `key_only` being true, `scan`-like requests will ignore values.
     ///
     /// By default, `key_only` is set to false.
@@ -258,10 +258,10 @@ impl Client {
     /// Create a new 'scan' request.
     ///
     /// Once resolved this request will result in a `Vec` of key-value pairs that lies in the specified range.
-    /// 
+    ///
     /// If the number of eligible key-value pairs are greater than `limit`,
     /// only the first `limit` pairs are returned, ordered by the key.
-    /// 
+    ///
     ///
     /// ```rust,no_run
     /// # use tikv_client::{KvPair, Config, RawClient, ToOwnedRange};
@@ -290,12 +290,12 @@ impl Client {
     /// Create a new 'batch scan' request.
     ///
     /// Once resolved this request will result in a set of scanners over the given keys.
-    /// 
-    /// **Warning**: This method is experimental. The `each_limit` parameter does not work as expected. 
-    /// It does not limit the number of results returned of each range, 
-    /// instead it limits the number of results in each region of each range. 
-    /// As a result, you may get **more than** `each_limit` key-value pairs for each range. 
-    /// But you should not miss any entries. 
+    ///
+    /// **Warning**: This method is experimental. The `each_limit` parameter does not work as expected.
+    /// It does not limit the number of results returned of each range,
+    /// instead it limits the number of results in each region of each range.
+    /// As a result, you may get **more than** `each_limit` key-value pairs for each range.
+    /// But you should not miss any entries.
     ///
     /// ```rust,no_run
     /// # use tikv_client::{Key, Config, RawClient, ToOwnedRange};

src/transaction/client.rs

@@ -17,12 +17,12 @@ const SCAN_LOCK_BATCH_SIZE: u32 = 1024; // TODO: cargo-culted value
 
 /// The TiKV transactional `Client` is used to interact with TiKV using transactional (MVCC) requests.
 ///
-/// A [`Transaction`](crate::transaction::Transaction) provides a SQL-like interface. 
+/// 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 
+/// 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:
@@ -71,7 +71,7 @@ impl Client {
     /// Creates a new [`Transaction`](Transaction) in optimistic mode.
     ///
     /// 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).
@@ -132,7 +132,7 @@ impl Client {
         self.pd.clone().get_timestamp().await
     }
 
-    /// Cleans MVCC records whose timestamp is lower than the given `timestamp` 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.
     ///

src/transaction/snapshot.rs

@@ -5,7 +5,11 @@ use derive_new::new;
 use futures::stream::BoxStream;
 use std::ops::RangeBounds;
 
-/// A readonly transaction which can have a custom timestamp.
+/// A read-only transaction which reads at the given timestamp.
+///
+/// It behaves as if the snapshot was taken at the given timestamp,
+/// i.e. it can read operations happened before the timestamp,
+/// but ignores operations after the timestamp.
 ///
 /// See the [Transaction](struct@crate::Transaction) docs for more information on the methods.
 #[derive(new)]
@@ -14,12 +18,12 @@ pub struct Snapshot {
 }
 
 impl Snapshot {
-    /// Gets the value associated with the given key.
+    /// Get the value associated with the given key.
     pub async fn get(&self, key: impl Into<Key>) -> Result<Option<Value>> {
         self.transaction.get(key).await
     }
 
-    /// Gets the values associated with the given keys.
+    /// Get the values associated with the given keys.
     pub async fn batch_get(
         &self,
         keys: impl IntoIterator<Item = impl Into<Key>>,
@@ -27,6 +31,7 @@ impl Snapshot {
         self.transaction.batch_get(keys).await
     }
 
+    /// Scan a range, return at most `limit` key-value pairs that lying in the range.
     pub async fn scan(
         &self,
         range: impl Into<BoundRange>,
@@ -35,7 +40,8 @@ impl Snapshot {
         self.transaction.scan(range, limit).await
     }
 
-    pub fn scan_reverse(&self, range: impl RangeBounds<Key>) -> BoxStream<Result<KvPair>> {
+    /// Unimplemented. Similar to scan, but in the reverse direction.
+    fn scan_reverse(&self, range: impl RangeBounds<Key>) -> BoxStream<Result<KvPair>> {
         self.transaction.scan_reverse(range)
     }
 }