From 91b73f9fc3c1bc281e85177808721b3efe37ece0 Mon Sep 17 00:00:00 2001
From: Matthias Vogelgesang <matthias.vogelgesang@gmail.com>
Date: Mon, 23 May 2022 21:30:06 +0200
Subject: [PATCH] docs: document Streaming::message() return values (#1006)

---
 tonic/src/codec/decode.rs | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/tonic/src/codec/decode.rs b/tonic/src/codec/decode.rs
index 66bc14e..2c0a2f8 100644
--- a/tonic/src/codec/decode.rs
+++ b/tonic/src/codec/decode.rs
@@ -136,6 +136,20 @@ impl<T> Streaming<T> {
 
 impl<T> Streaming<T> {
     /// Fetch the next message from this stream.
+    ///
+    /// # Return value
+    ///
+    /// - `Result::Err(val)` means a gRPC error was sent by the sender instead
+    /// of a valid response message. Refer to [`Status::code`] and
+    /// [`Status::message`] to examine possible error causes.
+    ///
+    /// - `Result::Ok(None)` means the stream was closed by the sender and no
+    /// more messages will be delivered. Further attempts to call
+    /// [`Streaming::message`] will result in the same return value.
+    ///
+    /// - `Result::Ok(Some(val))` means the sender streamed a valid response
+    /// message `val`.
+    ///
     /// ```rust
     /// # use tonic::{Streaming, Status, codec::Decoder};
     /// # use std::fmt::Debug;