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
2019-09-25 11:36:23 -04:00
parent 25e4dcc5d9
commit 646796f248
5 changed files with 45 additions and 2 deletions
@@ -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();

@@ -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
@@ -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(),
@@ -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(),
@@ -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,