Polish docs of clients and config

Signed-off-by: Nick Cameron <nrc@ncameron.org>

Author: nrc

src/config.rs

@@ -3,22 +3,11 @@
 use serde_derive::{Deserialize, Serialize};
 use std::{path::PathBuf, time::Duration};
 
-/// The configuration for either a `raw::Client` or a `transaction::Client`.
+/// The configuration for either a [`RawClient`](crate::RawClient) or a
+/// [`TransactionClient`](crate::TransactionClient).
 ///
-/// Because TiKV is managed by a [PD](https://github.com/pingcap/pd/) cluster, the endpoints for PD
-/// must be provided, **not** the TiKV nodes.
-///
-/// It's important to **include more than one PD endpoint** (include all, if possible!)
-/// This helps avoid having a *single point of failure*.
-///
-/// By default, this client will use an insecure connection over instead of one protected by
-/// Transport Layer Security (TLS). Your deployment may have chosen to rely on security measures
-/// such as a private network, or a VPN layer to provide secure transmission.
-///
-/// To use a TLS secured connection, use the `with_security` function to set the required
-/// parameters.
-///
-/// TiKV does not currently offer encrypted storage (or encryption-at-rest).
+/// See also [`TransactionOptions`](crate::TransactionOptions) which provides more ways to configure
+/// requests.
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 #[serde(default)]
 #[serde(rename_all = "kebab-case")]
@@ -43,11 +32,16 @@ impl Default for Config {
 }
 
 impl Config {
-    /// Set the certificate authority, certificate, and key locations for the
-    /// [`Config`](Config).
+    /// Set the certificate authority, certificate, and key locations for clients.
     ///
-    /// By default, TiKV connections do not utilize transport layer security. Enable it by setting
-    /// these values.
+    /// By default, this client will use an insecure connection over instead of one protected by
+    /// Transport Layer Security (TLS). Your deployment may have chosen to rely on security measures
+    /// such as a private network, or a VPN layer to provide secure transmission.
+    ///
+    /// To use a TLS secured connection, use the `with_security` function to set the required
+    /// parameters.
+    ///
+    /// TiKV does not currently offer encrypted storage (or encryption-at-rest).
     ///
     /// # Examples
     /// ```rust
@@ -66,16 +60,21 @@ impl Config {
         self
     }
 
-    /// Set the timeout for the [`Config`](Config).
+    /// Set the timeout for clients.
+    ///
+    /// The timeout is used for all requests when using or connecting to a TiKV cluster (including
+    /// PD nodes). If the request does not complete within timeout, the request is cancelled and
+    /// an error returned to the user.
     ///
+    /// The default timeout is two seconds.
     ///
     /// # Examples
     /// ```rust
     /// # use tikv_client::Config;
     /// # use std::time::Duration;
-    /// let config = Config::default().timeout(Duration::from_secs(10));
+    /// let config = Config::default().with_timeout(Duration::from_secs(10));
     /// ```
-    pub fn timeout(mut self, timeout: Duration) -> Self {
+    pub fn with_timeout(mut self, timeout: Duration) -> Self {
         self.timeout = timeout;
         self
     }

src/lib.rs

@@ -62,24 +62,32 @@
 //!
 //! Raw mode:
 //!
-//! ```rust
-//! use tikv_client::RawClient;
-//!
+//! ```rust,no_run
+//! # use tikv_client::{RawClient, Result};
+//! # use futures::prelude::*;
+//! # fn main() -> Result<()> {
+//! # futures::executor::block_on(async {
 //! let client = RawClient::new(vec!["127.0.0.1:2379"]).await?;
 //! client.put("key".to_owned(), "value".to_owned()).await?;
 //! let value = client.get("key".to_owned()).await?;
+//! # Ok(())
+//! # })}
 //! ```
 //!
 //! Transactional mode:
 //!
-//! ```rust
-//! use tikv_client::TransactionClient;
-//!
+//! ```rust,no_run
+//! # use tikv_client::{TransactionClient, Result};
+//! # use futures::prelude::*;
+//! # fn main() -> Result<()> {
+//! # futures::executor::block_on(async {
 //! let txn_client = TransactionClient::new(vec!["127.0.0.1:2379"]).await?;
 //! let mut txn = txn_client.begin_optimistic().await?;
 //! txn.put("key".to_owned(), "value".to_owned()).await?;
 //! let value = txn.get("key".to_owned()).await?;
 //! txn.commit().await?;
+//! # Ok(())
+//! # })}
 //! ```
 
 #[macro_use]

src/raw/client.rs

@@ -19,7 +19,8 @@ const MAX_RAW_KV_SCAN_LIMIT: u32 = 10240;
 /// 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.
+/// The returned results of raw request methods are [`Future`](std::future::Future)s that must be
+/// awaited to execute.
 #[derive(Clone)]
 pub struct Client {
     rpc: Arc<PdRpcClient>,
@@ -29,14 +30,16 @@ pub struct Client {
 }
 
 impl Client {
-    /// Create a raw [`Client`](Client).
+    /// Create a raw [`Client`] and connect to the TiKV cluster.
     ///
-    /// It's important to **include more than one PD endpoint** (include all, if possible!)
-    /// This helps avoid having a *single point of failure*.
+    /// Because TiKV is managed by a [PD](https://github.com/pingcap/pd/) cluster, the endpoints for
+    /// PD must be provided, not the TiKV nodes. It's important to include more than one PD endpoint
+    /// (include all endpoints, if possible), this helps avoid having a single point of failure.
     ///
     /// # Examples
+    ///
     /// ```rust,no_run
-    /// # use tikv_client::{Config, RawClient};
+    /// # use tikv_client::RawClient;
     /// # use futures::prelude::*;
     /// # futures::executor::block_on(async {
     /// let client = RawClient::new(vec!["192.168.0.100"]).await.unwrap();
@@ -46,17 +49,23 @@ impl Client {
         Self::new_with_config(pd_endpoints, Config::default()).await
     }
 
-    /// Create a raw [`Client`](Client).
+    /// Create a raw [`Client`] with a custom configuration, and connect to the TiKV cluster.
     ///
-    /// It's important to **include more than one PD endpoint** (include all, if possible!)
-    /// This helps avoid having a *single point of failure*.
+    /// Because TiKV is managed by a [PD](https://github.com/pingcap/pd/) cluster, the endpoints for
+    /// PD must be provided, not the TiKV nodes. It's important to include more than one PD endpoint
+    /// (include all endpoints, if possible), this helps avoid having a single point of failure.
     ///
     /// # Examples
+    ///
     /// ```rust,no_run
     /// # use tikv_client::{Config, RawClient};
     /// # use futures::prelude::*;
+    /// # use std::time::Duration;
     /// # futures::executor::block_on(async {
-    /// let client = RawClient::new(vec!["192.168.0.100"]).await.unwrap();
+    /// let client = RawClient::new_with_config(
+    ///     vec!["192.168.0.100"],
+    ///     Config::default().with_timeout(Duration::from_secs(60)),
+    /// ).await.unwrap();
     /// # });
     /// ```
     pub async fn new_with_config<S: Into<String>>(
@@ -72,22 +81,27 @@ impl Client {
         })
     }
 
-    /// Set the column family of requests.
-    ///
-    /// This function returns a new `Client`, requests created with it will have the
-    /// supplied column family constraint. The original `Client` can still be used.
+    /// Create a new client which is a clone of `self`, but which uses an explicit column family for
+    /// all requests.
     ///
-    /// By default, raw client uses the `Default` column family.
+    /// This function returns a new `Client`; requests created with the new client will use the
+    /// supplied column family. The original `Client` can still be used (without the new
+    /// column family).
     ///
-    /// For normal users of the raw API, you don't need to use other column families.
+    /// By default, raw clients use the `Default` column family.
     ///
     /// # Examples
+    ///
     /// ```rust,no_run
     /// # use tikv_client::{Config, RawClient, ColumnFamily};
     /// # use futures::prelude::*;
     /// # use std::convert::TryInto;
     /// # futures::executor::block_on(async {
-    /// let client = RawClient::new(vec!["192.168.0.100"]).await.unwrap().with_cf(ColumnFamily::Write);
+    /// let client = RawClient::new(vec!["192.168.0.100"])
+    ///     .await
+    ///     .unwrap()
+    ///     .with_cf(ColumnFamily::Write);
+    /// // Fetch a value at "foo" from the Write CF.
     /// let get_request = client.get("foo".to_owned());
     /// # });
     /// ```
@@ -411,11 +425,11 @@ impl Client {
     ///
     /// 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,
+    /// **Warning**: This method is experimental.
+    /// The `each_limit` parameter 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.
+    /// As a result, you may get **more than** `each_limit` key-value pairs for each range,
+    /// but you should not miss any entries.
     ///
     /// # Examples
     /// ```rust,no_run