Add more warnings and clean up

tonic/src/body.rs

@@ -1,3 +1,8 @@
+//! HTTP specific body utilities.
+//!
+//! This module contains traits and helper types to work with http bodies. Most
+//! of the types in this module are based around [`http_body::Body`].
+
 use crate::{Error, Status};
 use bytes::{Buf, Bytes, IntoBuf};
 use http_body::Body as HttpBody;
@@ -9,17 +14,29 @@ use std::{
 
 pub(crate) type BytesBuf = <Bytes as IntoBuf>::Buf;
 
+/// A trait alias for [`http_body::Body`].
 pub trait Body: sealed::Sealed {
+    /// The body data type.
     type Data: Buf;
+    /// The errors produced from the body.
     type Error: Into<Error>;
 
+    /// Check if the stream is over or not.
+    ///
+    /// Reference [`http_body::Body::is_end_stream`].
     fn is_end_stream(&self) -> bool;
 
+    /// Poll for more data from the body.
+    ///
+    /// Reference [`http_body::Body::poll_data`].
     fn poll_data(
         self: Pin<&mut Self>,
         cx: &mut Context<'_>,
     ) -> Poll<Option<Result<Self::Data, Self::Error>>>;
 
+    /// Poll for the trailing headers.
+    ///
+    /// Reference [`http_body::Body::poll_trailers`].
     fn poll_trailers(
         self: Pin<&mut Self>,
         cx: &mut Context<'_>,
@@ -164,7 +181,7 @@ where
 }
 
 impl fmt::Debug for BoxBody {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("BoxBody").finish()
     }
 }

tonic/src/client/grpc.rs

@@ -203,7 +203,7 @@ impl<T: Clone> Clone for Grpc<T> {
 }
 
 impl<T> fmt::Debug for Grpc<T> {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("Grpc").finish()
     }
 }

tonic/src/codec/decode.rs

@@ -90,10 +90,16 @@ impl<T> Streaming<T> {
 }
 
 impl<T> Streaming<T> {
+    /// Fetch the next message from this stream.
     pub async fn message(&mut self) -> Option<Result<T, Status>> {
         future::poll_fn(|cx| Pin::new(&mut *self).poll_next(cx)).await
     }
 
+    /// Fetch the trailing metadata.
+    ///
+    /// This will drain the stream of all its messages to recieve the trailing
+    /// metadata. If [`Streaming::message`] returns `None` then this function
+    /// will not need to poll for trailers since the body was totally consumed.
     pub async fn trailers(&mut self) -> Result<Option<MetadataMap>, Status> {
         // Shortcut to see if we already pulled the trailers in the stream step
         // we need to do that so that the stream can error on trailing grpc-status
@@ -243,7 +249,7 @@ impl<T> Stream for Streaming<T> {
 }
 
 impl<T> fmt::Debug for Streaming<T> {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("Streaming").finish()
     }
 }

tonic/src/codec/encode.rs

@@ -9,7 +9,7 @@ use std::pin::Pin;
 use std::task::{Context, Poll};
 use tokio_codec::Encoder;
 
-pub fn encode_server<T, U>(
+pub(crate) fn encode_server<T, U>(
     encoder: T,
     source: U,
 ) -> EncodeBody<impl Stream<Item = Result<BytesBuf, Status>>>
@@ -21,7 +21,7 @@ where
     EncodeBody::new_server(stream)
 }
 
-pub fn encode_client<T, U>(
+pub(crate) fn encode_client<T, U>(
     encoder: T,
     source: U,
 ) -> EncodeBody<impl Stream<Item = Result<BytesBuf, Status>>>
@@ -77,7 +77,7 @@ enum Role {
 
 #[pin_project]
 #[derive(Debug)]
-pub struct EncodeBody<S> {
+pub(crate) struct EncodeBody<S> {
     #[pin]
     inner: S,
     error: Option<Status>,

tonic/src/lib.rs

@@ -1,5 +1,10 @@
 #![recursion_limit = "512"]
-#![warn(missing_debug_implementations)]
+#![warn(
+    missing_debug_implementations,
+    missing_docs,
+    rust_2018_idioms,
+    unreachable_pub
+)]
 
 //! gRPC implementation
 

tonic/src/metadata/encoding.rs

@@ -52,8 +52,10 @@ pub trait ValueEncoding: Clone + Eq + PartialEq + Hash + self::value_encoding::S
 }
 
 #[derive(Clone, Debug, Eq, PartialEq, Hash)]
+#[doc(hidden)]
 pub enum Ascii {}
 #[derive(Clone, Debug, Eq, PartialEq, Hash)]
+#[doc(hidden)]
 pub enum Binary {}
 
 // ===== impl ValueEncoding =====

tonic/src/metadata/key.rs

@@ -28,7 +28,9 @@ pub struct InvalidMetadataKey {
     _priv: (),
 }
 
+/// An ascii metadata key.
 pub type AsciiMetadataKey = MetadataKey<Ascii>;
+/// A binary metadata key.
 pub type BinaryMetadataKey = MetadataKey<Binary>;
 
 impl<VE: ValueEncoding> MetadataKey<VE> {
@@ -175,6 +177,7 @@ impl<VE: ValueEncoding> fmt::Display for MetadataKey<VE> {
 }
 
 impl InvalidMetadataKey {
+    #[doc(hidden)]
     pub fn new() -> InvalidMetadataKey {
         InvalidMetadataKey { _priv: () }
     }

tonic/src/metadata/map.rs

@@ -1,6 +1,6 @@
-pub use self::as_encoding_agnostic_metadata_key::AsEncodingAgnosticMetadataKey;
-pub use self::as_metadata_key::AsMetadataKey;
-pub use self::into_metadata_key::IntoMetadataKey;
+pub(crate) use self::as_encoding_agnostic_metadata_key::AsEncodingAgnosticMetadataKey;
+pub(crate) use self::as_metadata_key::AsMetadataKey;
+pub(crate) use self::into_metadata_key::IntoMetadataKey;
 
 use super::encoding::{Ascii, Binary, ValueEncoding};
 use super::key::{InvalidMetadataKey, MetadataKey};
@@ -49,7 +49,9 @@ pub struct Iter<'a> {
 /// to either an ascii or a binary ("*-bin") key.
 #[derive(Debug)]
 pub enum KeyAndValueRef<'a> {
+    /// An ascii metadata key and value.
     Ascii(&'a MetadataKey<Ascii>, &'a MetadataValue<Ascii>),
+    /// A binary metadata key and value.
     Binary(&'a MetadataKey<Binary>, &'a MetadataValue<Binary>),
 }
 
@@ -57,7 +59,9 @@ pub enum KeyAndValueRef<'a> {
 /// to either an ascii or a binary ("*-bin") key.
 #[derive(Debug)]
 pub enum KeyAndMutValueRef<'a> {
+    /// An ascii metadata key and value.
     Ascii(&'a MetadataKey<Ascii>, &'a mut MetadataValue<Ascii>),
+    /// A binary metadata key and value.
     Binary(&'a MetadataKey<Binary>, &'a mut MetadataValue<Binary>),
 }
 
@@ -90,7 +94,9 @@ pub struct Keys<'a> {
 /// to either an ascii or a binary ("*-bin") key.
 #[derive(Debug)]
 pub enum KeyRef<'a> {
+    /// An ascii metadata key and value.
     Ascii(&'a MetadataKey<Ascii>),
+    /// A binary metadata key and value.
     Binary(&'a MetadataKey<Binary>),
 }
 
@@ -109,7 +115,9 @@ pub struct Values<'a> {
 /// to either an ascii or a binary ("*-bin" key) value.
 #[derive(Debug)]
 pub enum ValueRef<'a> {
+    /// An ascii metadata key and value.
     Ascii(&'a MetadataValue<Ascii>),
+    /// A binary metadata key and value.
     Binary(&'a MetadataValue<Binary>),
 }
 
@@ -127,7 +135,9 @@ pub struct ValuesMut<'a> {
 /// to either an ascii or a binary ("*-bin" key) value.
 #[derive(Debug)]
 pub enum ValueRefMut<'a> {
+    /// An ascii metadata key and value.
     Ascii(&'a mut MetadataValue<Ascii>),
+    /// A binary metadata key and value.
     Binary(&'a mut MetadataValue<Binary>),
 }
 

tonic/src/metadata/value.rs

@@ -33,7 +33,9 @@ pub struct ToStrError {
     _priv: (),
 }
 
+/// An ascii metadata value.
 pub type AsciiMetadataValue = MetadataValue<Ascii>;
+/// A binary metadata value.
 pub type BinaryMetadataValue = MetadataValue<Binary>;
 
 impl<VE: ValueEncoding> MetadataValue<VE> {

tonic/src/request.rs

@@ -54,7 +54,7 @@ impl<T> Request<T> {
         Request::from_http_parts(parts, message)
     }
 
-    pub fn into_http(self, uri: http::Uri) -> http::Request<T> {
+    pub(crate) fn into_http(self, uri: http::Uri) -> http::Request<T> {
         let mut request = http::Request::new(self.message);
 
         *request.version_mut() = http::Version::HTTP_2;
@@ -65,6 +65,7 @@ impl<T> Request<T> {
         request
     }
 
+    #[doc(hidden)]
     pub fn map<F, U>(self, f: F) -> Request<U>
     where
         F: FnOnce(T) -> U,

tonic/src/response.rs

@@ -16,6 +16,7 @@ impl<T> Response<T> {
         }
     }
 
+    /// Get a immutable reference to `T`.
     pub fn get_ref(&self) -> &T {
         &self.message
     }
@@ -56,7 +57,7 @@ impl<T> Response<T> {
         }
     }
 
-    pub fn into_http(self) -> http::Response<T> {
+    pub(crate) fn into_http(self) -> http::Response<T> {
         let mut res = http::Response::new(self.message);
 
         *res.version_mut() = http::Version::HTTP_2;
@@ -65,6 +66,7 @@ impl<T> Response<T> {
         res
     }
 
+    #[doc(hidden)]
     pub fn map<F, U>(self, f: F) -> Response<U>
     where
         F: FnOnce(T) -> U,

tonic/src/server/grpc.rs

@@ -61,7 +61,7 @@ where
         self.map_response(response)
     }
 
-    // Handle a server side streaming request.
+    /// Handle a server side streaming request.
     pub async fn server_streaming<S, B>(
         &mut self,
         mut service: S,
@@ -202,7 +202,7 @@ where
 }
 
 impl<T> fmt::Debug for Grpc<T> {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("Grpc").finish()
     }
 }

tonic/src/status.rs

@@ -21,6 +21,7 @@ pub struct Status {
 
 /// gRPC status codes used by `Status`.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
+#[allow(missing_docs)]
 pub enum Code {
     Ok = 0,
     Cancelled = 1,

tonic/src/transport/channel.rs

@@ -119,7 +119,7 @@ impl Builder {
 }
 
 impl fmt::Debug for Channel {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("Channel").finish()
     }
 }

tonic/src/transport/mod.rs

@@ -1,3 +1,6 @@
+// TODO: write transport docs.
+#![allow(missing_docs)]
+
 mod channel;
 mod endpoint;
 mod server;
@@ -40,7 +43,7 @@ impl From<(ErrorKind, crate::Error)> for Error {
 }
 
 impl fmt::Debug for Error {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         let mut f = f.debug_tuple("Error");
         f.field(&self.kind);
         if let Some(source) = &self.source {
@@ -51,7 +54,7 @@ impl fmt::Debug for Error {
 }
 
 impl fmt::Display for Error {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         if let Some(source) = &self.source {
             write!(f, "{}: {}", self.kind, source)
         } else {
@@ -69,7 +72,7 @@ impl error::Error for Error {
 }
 
 impl fmt::Display for ErrorKind {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(f, "{:?}", self)
     }
 }

tonic/src/transport/server.rs

@@ -94,7 +94,7 @@ fn incoming(
 
 // TODO: add custom tracing here
 #[derive(Debug)]
-pub struct Svc<S>(S);
+pub(crate) struct Svc<S>(S);
 
 impl<S> Service<Request<Body>> for Svc<S>
 where
@@ -113,7 +113,7 @@ where
     }
 }
 
-pub struct MakeSvc<M>(M);
+pub(crate) struct MakeSvc<M>(M);
 
 impl<M, S, T> Service<T> for MakeSvc<M>
 where

tonic/src/transport/service/add_origin.rs

@@ -3,13 +3,13 @@ use std::task::{Context, Poll};
 use tower_service::Service;
 
 #[derive(Debug)]
-pub struct AddOrigin<T> {
+pub(crate) struct AddOrigin<T> {
     inner: T,
     origin: Uri,
 }
 
 impl<T> AddOrigin<T> {
-    pub fn new(inner: T, origin: Uri) -> Self {
+    pub(crate) fn new(inner: T, origin: Uri) -> Self {
         Self { inner, origin }
     }
 }

tonic/src/transport/service/boxed.rs

@@ -6,12 +6,12 @@ use std::{
 use tower_service::Service;
 
 #[derive(Debug, Clone)]
-pub struct BoxService<S> {
+pub(crate) struct BoxService<S> {
     inner: S,
 }
 
 impl<S> BoxService<S> {
-    pub fn new(inner: S) -> Self {
+    pub(crate) fn new(inner: S) -> Self {
         Self { inner }
     }
 }

tonic/src/transport/service/connect.rs

@@ -1,4 +1,4 @@
-use super::{add_origin::AddOrigin, connector::Connector};
+use super::{AddOrigin, Connector};
 use crate::{transport::Endpoint, BoxBody};
 use http::{Request, Response, Uri};
 use hyper::client::conn::Builder;
@@ -56,7 +56,7 @@ impl Load for Connection {
 }
 
 impl fmt::Debug for Connection {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("Connection").finish()
     }
 }

tonic/src/transport/service/connector.rs

@@ -10,13 +10,13 @@ use tower_service::Service;
 
 type ConnectFuture = <HttpConnector as MakeConnection<Uri>>::Future;
 
-pub struct Connector {
+pub(crate) struct Connector {
     http: HttpConnector,
     tls: Option<TlsConnector>,
 }
 
 impl Connector {
-    pub fn new(cert: Option<Cert>) -> Result<Self, crate::Error> {
+    pub(crate) fn new(cert: Option<Cert>) -> Result<Self, crate::Error> {
         let mut http = HttpConnector::new();
         http.enforce_http(false);
 

tonic/src/transport/service/io.rs

@@ -10,7 +10,7 @@ pub(in crate::transport) trait Io:
 
 impl<T> Io for T where T: AsyncRead + AsyncWrite + Send + Unpin + 'static {}
 
-pub struct BoxedIo(Pin<Box<dyn Io>>);
+pub(crate) struct BoxedIo(Pin<Box<dyn Io>>);
 
 impl BoxedIo {
     pub(in crate::transport) fn new<I: Io>(io: I) -> Self {

tonic/src/transport/service/mod.rs

@@ -5,8 +5,9 @@ mod connector;
 mod discover;
 mod io;
 
-pub use self::add_origin::AddOrigin;
-pub use self::boxed::BoxService;
-pub use self::connect::Connection;
-pub use self::discover::ServiceList;
-pub use self::io::BoxedIo;
+pub(crate) use self::add_origin::AddOrigin;
+pub(crate) use self::boxed::BoxService;
+pub(crate) use self::connect::Connection;
+pub(crate) use self::connector::Connector;
+pub(crate) use self::discover::ServiceList;
+pub(crate) use self::io::BoxedIo;

tonic/src/transport/tls/mod.rs

@@ -12,40 +12,40 @@ mod imp;
 use tokio::net::TcpStream;
 
 #[derive(Debug, Clone)]
-pub struct Cert {
+pub(crate) struct Cert {
     pub(crate) ca: Vec<u8>,
     pub(crate) key: Option<Vec<u8>>,
     pub(crate) domain: String,
 }
 
 #[derive(Clone)]
-pub struct TlsConnector {
+pub(crate) struct TlsConnector {
     inner: imp::TlsConnector,
 }
 
 impl TlsConnector {
-    pub fn new(cert: Cert) -> Result<Self, crate::Error> {
+    pub(crate) fn new(cert: Cert) -> Result<Self, crate::Error> {
         let inner = imp::TlsConnector::new(cert)?;
         Ok(Self { inner })
     }
 
-    pub async fn connect(&self, io: TcpStream) -> Result<imp::TlsStream, crate::Error> {
+    pub(crate) async fn connect(&self, io: TcpStream) -> Result<imp::TlsStream, crate::Error> {
         self.inner.connect(io).await
     }
 }
 
 #[derive(Clone)]
-pub struct TlsAcceptor {
+pub(crate) struct TlsAcceptor {
     inner: imp::TlsAcceptor,
 }
 
 impl TlsAcceptor {
-    pub fn new(cert: Cert) -> Result<Self, crate::Error> {
+    pub(crate) fn new(cert: Cert) -> Result<Self, crate::Error> {
         let inner = imp::TlsAcceptor::new(cert)?;
         Ok(Self { inner })
     }
 
-    pub async fn connect(&self, io: TcpStream) -> Result<imp::TlsStream, crate::Error> {
+    pub(crate) async fn connect(&self, io: TcpStream) -> Result<imp::TlsStream, crate::Error> {
         self.inner.connect(io).await
     }
 }

tonic/src/transport/tls/openssl.rs

@@ -7,16 +7,16 @@ use tokio_openssl::SslStream;
 
 const ALPN_H2: &[u8] = b"\x02h2";
 
-pub type TlsStream = SslStream<TcpStream>;
+pub(crate) type TlsStream = SslStream<TcpStream>;
 
 #[derive(Clone)]
-pub struct TlsConnector {
+pub(crate) struct TlsConnector {
     config: SslConnector,
     domain: Arc<String>,
 }
 
 impl TlsConnector {
-    pub fn new(cert: Cert) -> Result<Self, crate::Error> {
+    pub(crate) fn new(cert: Cert) -> Result<Self, crate::Error> {
         let Cert { ca, domain, .. } = cert;
         let mut config = SslConnector::builder(SslMethod::tls()).unwrap();
 
@@ -34,7 +34,7 @@ impl TlsConnector {
         })
     }
 
-    pub async fn connect(&self, io: TcpStream) -> Result<TlsStream, crate::Error> {
+    pub(crate) async fn connect(&self, io: TcpStream) -> Result<TlsStream, crate::Error> {
         let config = self.config.configure()?;
         let tls = tokio_openssl::connect(config, &self.domain, io).await?;
         Ok(tls)
@@ -42,12 +42,12 @@ impl TlsConnector {
 }
 
 #[derive(Clone)]
-pub struct TlsAcceptor {
+pub(crate) struct TlsAcceptor {
     config: SslAcceptor,
 }
 
 impl TlsAcceptor {
-    pub fn new(cert: Cert) -> Result<Self, crate::Error> {
+    pub(crate) fn new(cert: Cert) -> Result<Self, crate::Error> {
         let Cert { ca, key, .. } = cert;
 
         let key = PKey::private_key_from_pem(&key.unwrap()[..])?;
@@ -64,7 +64,7 @@ impl TlsAcceptor {
         })
     }
 
-    pub async fn connect(&self, io: TcpStream) -> Result<TlsStream, crate::Error> {
+    pub(crate) async fn connect(&self, io: TcpStream) -> Result<TlsStream, crate::Error> {
         let config = self.config.clone();
         let tls = tokio_openssl::accept(&config, io).await?;
         Ok(tls)