Add README and some lib.rs docs

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

Author: Hoverbear

README.md

@@ -0,0 +1,37 @@
+# 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 (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 Rust bindings to [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, depend on it in the `Cargo.toml` of your Rust project:
+
+```toml
+[dependencies]
+# ...Your other dependencies...
+tikv-client = "~0.1"
+```
+
+## Access the documentation
+
+We reccomend using the autogenerated to browse and understand the API. We've done our best to include ample, tested, and understandable examples.
+
+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.
+```
+
+Otherwise, you can visit [docs.rs/tikv-client](https://docs.rs/tikv-client/).

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 Rust bindings to [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, depend on it 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 give a `cargo build --package tikv-client` 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 `pd`
+//! 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-View
+//! 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.
+//!
+//! ```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 advisible to use the 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 advisible to use the 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;