Add more docs

tonic/src/lib.rs

@@ -5,8 +5,30 @@
     rust_2018_idioms,
     unreachable_pub
 )]
+#![doc(test(no_crate_inject, attr(deny(rust_2018_idioms))))]
 
-//! gRPC implementation
+//! 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
+//! performance**, **interoperability**, and **flexibility**. This library was
+//! created to have first class support of async/await.
+//!
+//! # Examples
+//!
+//! Examples can be found in the [`tonic-examples`] crate.
+//!
+//! # Generic implementation
+//!
+//! TODO: write generic implementation docs
+//!
+//! # Transport
+//!
+//! TODO: write transport docs
+//!
+//! [gRPC]: https://grpc.io
+//! [tonic]: https://github.com/hyperium/tonic
+//! [`tonic-examples`]: https://github.com/hyperium/tonic/tree/master/tonic-examples/src
 
 pub mod body;
 pub mod client;

tonic/src/status.rs

@@ -8,7 +8,7 @@ const GRPC_STATUS_HEADER_CODE: &str = "grpc-status";
 const GRPC_STATUS_MESSAGE_HEADER: &str = "grpc-message";
 const GRPC_STATUS_DETAILS_HEADER: &str = "grpc-status-details-bin";
 
-/// A gRPC "status" describing the result of an RPC call.
+/// A gRPC status describing the result of an RPC call.
 #[derive(Clone)]
 pub struct Status {
     /// The gRPC status code, found in the `grpc-status` header.
@@ -19,7 +19,11 @@ pub struct Status {
     details: Bytes,
 }
 
-/// gRPC status codes used by `Status`.
+/// gRPC status codes used by [`Status`].
+///
+/// These variants match the [gRPC status codes].
+///
+/// [gRPC status codes]: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md#status-codes-and-their-use-in-grpc
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 #[allow(missing_docs)]
 pub enum Code {

tonic/src/transport/mod.rs

@@ -1,6 +1,7 @@
-// TODO: write transport docs.
 #![allow(missing_docs)]
 
+//! TODO: write transport docs.
+
 mod channel;
 mod endpoint;
 mod server;