add more docs

tonic/Cargo.toml

@@ -4,6 +4,21 @@ version = "0.1.0-alpha.1"
 authors = ["Lucio Franco <[email protected]>"]
 edition = "2018"
 
+[features]
+default = ["transport", "codegen", "prost"]
+codegen = ["async-trait"]
+transport = [
+    "hyper",
+    "tokio",
+    "tower",
+    "tower-reconnect",
+    "tower-balance",
+    "tower-load",
+]
+openssl = ["openssl1", "tokio-openssl", "tls"]
+rustls = ["tokio-rustls", "tls"]
+tls = []
+
 [dependencies]
 futures-core-preview = "=0.3.0-alpha.18"
 futures-util-preview = "=0.3.0-alpha.18"
@@ -40,18 +55,3 @@ openssl1 = { package = "openssl", version = "0.10", optional = true }
 
 # rustls
 tokio-rustls = { version = "0.12.0-alpha.2", optional = true }
-
-[features]
-default = ["transport", "codegen", "prost"]
-codegen = ["async-trait"]
-transport = [
-    "hyper",
-    "tokio",
-    "tower",
-    "tower-reconnect",
-    "tower-balance",
-    "tower-load",
-]
-openssl = ["openssl1", "tokio-openssl", "tls"]
-rustls = ["tokio-rustls", "tls"]
-tls = []

tonic/src/lib.rs

@@ -9,17 +9,22 @@
 #![doc(html_root_url = "https://docs.rs/tonic/0.1.0")]
 #![doc(test(no_crate_inject, attr(deny(rust_2018_idioms))))]
 
-//! A rust implementation of [gRPC], a high performance, open source, general
+//! A Rust implementation of [gRPC], a high performance, open source, general
 //! RPC framework that puts mobile and HTTP/2 first.
 //!
-//! [tonic] is a gRPC over HTTP2 implementation focused on **high
+//! [`tonic`] is a gRPC over HTTP/2 implementation focused on **high
 //! performance**, **interoperability**, and **flexibility**. This library was
-//! created to have first class support of async/await.
+//! created to have first class support of async/await and to act as a core building
+//! block for production systems written in Rust.
 //!
 //! # Examples
 //!
 //! Examples can be found in the [`tonic-examples`] crate.
 //!
+//! # Getting Started
+//!
+//! Follow the instructions in the [`tonic-build`] crate documentation.
+//!
 //! # Feature Flags
 //!
 //! - `transport`: Enables the fully featured, batteries included client and server
@@ -36,18 +41,30 @@
 //!
 //! ## Generic implementation
 //!
-//! The main goal of [`tonic`] is to provide a generic gRPC implementation over http2.0
+//! The main goal of [`tonic`] is to provide a generic gRPC implementation over HTTP/2
-//! framing. This means at the lowest level this library provides the ability to
+//! framing. This means at the lowest level this library provides the ability to use
+//! a generic HTTP/2 implementation with different types of gRPC encodings formats. Generally,
+//! some form of codegen should be used instead of interacting directly with the items in
+//! [`client`] and [`server`].
 //!
-//! TODO: write generic implementation docs
+//! ## Transport
 //!
-//! # Transport
+//! The [`transport`] module contains a fully featured HTTP/2.0 [`Channel`] (gRPC terminology)
-//!
+//! and [`Server`]. These implementations are built on top of [`tokio`], [`hyper`] and [`tower`].
-//! TODO: write transport docs
+//! It also provides many of the features that the core gRPC libraries provide such as load balancing,
+//! tls, timeouts, and many more. This implementation can also be used as a reference implementation
+//! to build even more feature rich clients and servers. This module also provides the ability to choose
+//! between [`rustls`] and [`openssl`] for the tls backend.
 //!
 //! [gRPC]: https://grpc.io
-//! [tonic]: https://github.com/hyperium/tonic
+//! [`tonic`]: https://github.com/hyperium/tonic
+//! [`tonic-build`]: https://docs.rs/tonic-build
 //! [`tonic-examples`]: https://github.com/hyperium/tonic/tree/master/tonic-examples/src
+//! [`Codec`]: codec/trait.Codec.html
+//! [`Channel`]: transport/struct.Channel.html
+//! [`Server`]: transport/struct.Server.html
+//! [`rustls`]: https://docs.rs/rustls
+//! [`openssl`]: https://www.openssl.org
 
 pub mod body;
 pub mod client;