From 646796f248805ab33ab16846ae18241ed1475f50 Mon Sep 17 00:00:00 2001
From: John Doneth <doneth7@gmail.com>
Date: Wed, 25 Sep 2019 11:36:23 -0400
Subject: [PATCH] Add some doc examples (#9)

* doc examples for tonic::Streaming

* from http doc

* more docs

* use same export pattern

* interceptor doc WIP

* remove unfinished doc examples

* recommended changes

* remove unnecessary prost refs
---
 tonic-build/src/lib.rs        |  1 -
 tonic/src/codec/decode.rs     | 22 ++++++++++++++++++++++
 tonic/src/request.rs          | 12 +++++++++++-
 tonic/src/response.rs         | 11 +++++++++++
 tonic/src/transport/server.rs |  1 +
 5 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/tonic-build/src/lib.rs b/tonic-build/src/lib.rs
index aa3ba8b..936af5f 100644
--- a/tonic-build/src/lib.rs
+++ b/tonic-build/src/lib.rs
@@ -67,7 +67,6 @@ impl Builder {
     }
 
     /// Compile the .proto files and execute code generation.
-    #[cfg_attr(not(feature = "rustfmt"), allow(unused_variables))]
     pub fn compile<P: AsRef<Path>>(self, protos: &[P], includes: &[P]) -> io::Result<()> {
         let mut config = Config::new();
 
diff --git a/tonic/src/codec/decode.rs b/tonic/src/codec/decode.rs
index 117ed64..c252449 100644
--- a/tonic/src/codec/decode.rs
+++ b/tonic/src/codec/decode.rs
@@ -91,6 +91,18 @@ impl<T> Streaming<T> {
 
 impl<T> Streaming<T> {
     /// Fetch the next message from this stream.
+    /// ```rust
+    /// # use tonic::{Streaming, Status};
+    /// # use std::fmt::Debug;
+    /// # async fn next_message_ex<T>(mut request: Streaming<T>) -> Result<(), Status>
+    /// # where T: Debug
+    /// # {
+    /// if let Some(next_message) = request.message().await? {
+    ///     println!("{:?}", next_message);
+    /// }
+    /// # Ok(())
+    /// # }
+    /// ```
     pub async fn message(&mut self) -> Result<Option<T>, Status> {
         match future::poll_fn(|cx| Pin::new(&mut *self).poll_next(cx)).await {
             Some(Ok(m)) => Ok(Some(m)),
@@ -104,6 +116,16 @@ impl<T> Streaming<T> {
     /// This will drain the stream of all its messages to receive the trailing
     /// metadata. If [`Streaming::message`] returns `None` then this function
     /// will not need to poll for trailers since the body was totally consumed.
+    ///    
+    /// ```rust
+    /// # use tonic::{Streaming, Status};
+    /// # async fn trailers_ex<T>(mut request: Streaming<T>) -> Result<(), Status> {
+    /// if let Some(metadata) = request.trailers().await? {
+    ///     println!("{:?}", metadata);
+    /// }
+    /// # Ok(())
+    /// # }
+    /// ```
     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
diff --git a/tonic/src/request.rs b/tonic/src/request.rs
index a73a790..2a46f10 100644
--- a/tonic/src/request.rs
+++ b/tonic/src/request.rs
@@ -8,7 +8,17 @@ pub struct Request<T> {
 }
 
 impl<T> Request<T> {
-    /// Create a new gRPC request
+    /// Create a new gRPC request.
+    ///
+    /// ```rust
+    /// # use tonic::Request;
+    /// # pub struct HelloRequest {
+    /// #   pub name: String,
+    /// # }
+    /// Request::new(HelloRequest {
+    ///    name: "Bob".into(),
+    /// });
+    /// ```
     pub fn new(message: T) -> Self {
         Request {
             metadata: MetadataMap::new(),
diff --git a/tonic/src/response.rs b/tonic/src/response.rs
index b30b895..cc9056f 100644
--- a/tonic/src/response.rs
+++ b/tonic/src/response.rs
@@ -9,6 +9,17 @@ pub struct Response<T> {
 
 impl<T> Response<T> {
     /// Create a new gRPC response.
+    ///
+    /// ```rust
+    /// # use tonic::Response;
+    /// # pub struct HelloReply {
+    /// #   pub message: String,
+    /// # }
+    /// # let name = "";
+    /// Response::new(HelloReply {
+    ///     message: format!("Hello, {}!", name).into(),
+    /// });
+    /// ```
     pub fn new(message: T) -> Self {
         Response {
             metadata: MetadataMap::new(),
diff --git a/tonic/src/transport/server.rs b/tonic/src/transport/server.rs
index c587397..e552b05 100644
--- a/tonic/src/transport/server.rs
+++ b/tonic/src/transport/server.rs
@@ -79,6 +79,7 @@ impl Builder {
     //     self
     // }
 
+    /// Intercept the execution of gRPC methods.
     pub fn interceptor_fn<F, Out>(&mut self, f: F) -> &mut Self
     where
         F: Fn(&mut BoxService, Request<Body>) -> Out + Send + Sync + 'static,