Add README and some lib.rs docs (#31)

* Add README and some lib.rs docs

Signed-off-by: Ana Hobden <operator@hoverbear.org>

* Apply suggestions from code review

Nit fixes.

Signed-off-by: Ana Hobden <operator@hoverbear.org>

* Nit fixes

Signed-off-by: Ana Hobden <operator@hoverbear.org>

Author: Hoverbear

README.md

@@ -0,0 +1,39 @@
+# TiKV Client (Rust)
+
+[![Build Status](https://travis-ci.org/tikv/client-rust.svg?branch=master)](https://travis-ci.org/pingcap/client-rust)
+[![Documentation](https://docs.rs/tikv-client/badge.svg)](https://docs.rs/tikv-client/)
+
+> Currently this crate is experimental and some portions (e.g. the Transactional API) are still in active development. You're encouraged to use this library for testing and to help us find problems!
+
+This crate provides a clean, ready to use client for [TiKV](https://github.com/tikv/tikv), a
+distributed transactional Key-Value database written in Rust.
+
+With this crate you can easily connect to any TiKV deployment, interact with it, and mutate the data it contains.
+
+This is an open source (Apache 2) project hosted by the Cloud Native Computing Foundation (CNCF) and maintained by the TiKV Authors. *We'd love it if you joined us in improving this project.*
+
+## Install
+
+There are no special requirements to use this. It is a Rust 2018 edition crate supporting stable and nightly.
+
+To use this crate in your project, add it as a dependency in the `Cargo.toml` of your Rust project:
+
+```toml
+[dependencies]
+# ...Your other dependencies...
+tikv-client = "~0.1"
+```
+
+## Access the documentation
+
+We recommend using the cargo-generated documentation to browse and understand the API. We've done
+our best to include ample, tested, and understandable examples.
+
+You can visit [docs.rs/tikv-client](https://docs.rs/tikv-client/), or build the documentation yourself.
+
+You can access the documentation on your machine by running the following in any project that depends on `tikv-client`.
+
+```bash
+cargo doc --package tikv-client --open
+# If it didn't work, browse file URL it tried to open with your browser.
+```

src/lib.rs

@@ -13,6 +13,102 @@
 #![recursion_limit = "128"]
 #![type_length_limit = "1572864"]
 
+//! TiKV Client for Rust.
+//!
+//! > Currently this crate is experimental and some portions (eg the Transactional API) are still
+//! > in active development. You're encouraged to use this library for testing and help us find
+//! > problems!
+//!
+//! This crate provides a clean, ready to use client for [TiKV](https://github.com/tikv/tikv), a
+//! distributed transactional Key-Value database written in Rust.
+//!
+//! With this crate you can easily connect to any TiKV deployment, interact with it, and mutate the
+//! data it contains.
+//!
+//! This is an open source (Apache 2) project hosted by the Cloud Native Computing Foundation
+//! (CNCF) and maintained by the TiKV Authors. *We'd love it if you joined us in improving this
+//! project.*
+//!
+//! ## Install
+//!
+//! There are no special requirements to use this. It is a Rust 2018 edition crate supporting
+//! stable and nightly.
+//!
+//! To use this crate in your project, add it as a dependency in the `Cargo.toml` of your Rust project:
+//!
+//! ```toml
+//! [dependencies]
+//! # ...Your other dependencies...
+//! tikv-client = "~0.1"
+//! futures = "0.1" # You'll need this later.
+//! ```
+//!
+//! Then run a `cargo build --package tikv-client` command to test building the crate.
+//!
+//! Next, you need to choose the API appropriate for your needs.
+//!
+//! ## Choosing an API
+//!
+//! This crate offers both [**raw**](raw/index.html) and
+//! [**transactional**](transaction/index.html) APIs. You should choose just one for your system.
+//!
+//! The *consequence* of supporting transactions is increased overhead of coordination with the
+//! placement driver for timestamp acquisition. This is approximately 1 RTT.
+//!
+//! *While it is possible to use both APIs at the same time, doing so is unsafe and unsupported.*
+//!
+//! Choose the one that suites your needs as described below, then add the import statement to your
+//! file where you need to use the library.
+//!
+//! ### Transactional
+//!
+//! The [transactional](transaction/index.html) API supports **transactions** via Multi-Version
+//! Concurrency Control (MVCC).
+//!
+//! **Best when you mostly do** complex sets of actions, actions which may require a rollback,
+//! operations affecting multiple keys or values, or operations that depend on strong ordering.
+//!
+//! ```rust
+//! use tikv_client::{*, transaction::*};
+//! ```
+//!
+//! ### Raw
+//!
+//! The [raw](raw/index.html) API has **reduced coordination overhead**, but lacks any
+//! transactional abilities.
+//!
+//! **Best when you mostly do** single row changes, and have very limited cross-row (eg. foreign
+//! key) requirements. You will not be able to use transactions with this API.
+//!
+//! ```rust
+//! use tikv_client::{*, raw::*};
+//! ```
+//!
+//! ## Connect
+//!
+//! Regardless of which API you choose, you'll need to connect your client
+//! ([raw](raw/struct.Client.html), [transactional](transaction/struct.Client.html)).
+//!
+//! ```rust
+//! # use tikv_client::{*, raw::*};
+//! use futures::Future;
+//!
+//! // Configure endpoints and optional TLS.
+//! let config = Config::new(vec![ // A list of PD endpoints.
+//!     "192.168.0.100:2379",
+//!     "192.168.0.101:2379",
+//! ]).with_security("root.ca", "internal.cert", "internal.key");
+//!
+//! // Get an unresolved connection.
+//! let connect = Client::new(&config);
+//!
+//! // Resolve the connection into a client.
+//! let client = connect.wait();
+//! ```
+//!
+//! At this point, you should seek the documentation in the related API modules.
+//!
+
 use futures::Future;
 use serde_derive::*;
 use std::{

src/raw.rs

@@ -11,15 +11,15 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-/// Raw related functionality.
-///
-/// Using the [`raw::Client`](struct.Client.html) you can utilize TiKV's raw interface.
-///
-/// This interface offers optimal performance as it does not require coordination with a timestamp
-/// oracle, while the transactional interface does.
-///
-/// **Warning:** It is not advisible to use the both raw and transactional functionality in the same keyspace.
-///
+//! Raw related functionality.
+//!
+//! Using the [`raw::Client`](struct.Client.html) you can utilize TiKV's raw interface.
+//!
+//! This interface offers optimal performance as it does not require coordination with a timestamp
+//! oracle, while the transactional interface does.
+//!
+//! **Warning:** It is not advisable to use both raw and transactional functionality in the same keyspace.
+//!
 use crate::{rpc::RpcClient, Config, Error, Key, KeyRange, KvFuture, KvPair, Result, Value};
 use futures::{future, Async, Future, Poll};
 use std::{
@@ -318,7 +318,7 @@ impl Deref for ColumnFamily {
     }
 }
 
-pub trait RequestInner: Sized {
+trait RequestInner: Sized {
     type Resp;
 
     fn execute(self, client: Arc<RpcClient>, cf: Option<ColumnFamily>) -> KvFuture<Self::Resp>;

src/transaction.rs

@@ -11,14 +11,15 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-/*! Transactional related functionality.
+//! Transactional related functionality.
+//!
+//! Using the [`transaction::Client`](struct.Client.html) you can utilize TiKV's transactional interface.
+//!
+//! This interface offers SQL-like transactions on top of the raw interface.
+//!
+//! **Warning:** It is not advisable to use both raw and transactional functionality in the same keyspace.
+//!
 
-Using the [`transaction::Client`](struct.Client.html) you can utilize TiKV's transactional interface.
-
-This interface offers SQL-like transactions on top of the raw interface.
-
-**Warning:** It is not advisible to use the both raw and transactional functionality in the same keyspace.
- */
 use crate::{Config, Error, Key, KvPair, Value};
 use futures::{Future, Poll, Stream};
 use std::ops::RangeBounds;