From 01fa7a4eaa046b6096390b5099aaac0e047e43f7 Mon Sep 17 00:00:00 2001
From: Floris Bruynooghe <flub@devork.be>
Date: Thu, 16 Feb 2023 20:59:03 +0100
Subject: [PATCH] improve wording, correct example

---
 quinn/src/recv_stream.rs | 29 +++++++++++++++++++----------
 1 file changed, 19 insertions(+), 10 deletions(-)

diff --git a/quinn/src/recv_stream.rs b/quinn/src/recv_stream.rs
index c62598bac..78e09a041 100644
--- a/quinn/src/recv_stream.rs
+++ b/quinn/src/recv_stream.rs
@@ -25,28 +25,36 @@ use crate::{
 ///
 /// When a stream is expected to be closed gracefully the sender should call
 /// [`SendStream::finish`].  However there is no guarantee the connected [`RecvStream`] will
-/// receive this End Of File (EOF) indicator in the same QUIC frame as the last frame which
+/// receive the "finished" notification in the same QUIC frame as the last frame which
 /// carried data.
 ///
-/// Even if the application layer logic already knows it read all the data because it
-/// does its own framing, it must still read from the [`RecvStream`] until EOF.  Otherwise
-/// it risks inadvertently calling [`RecvStream::stop`] if it drops the stream.  And calling
-/// [`RecvStream::stop`] could result in the connected [`SendStream::finish`] call failing
-/// with a [`WriteError::Stopped`] error.
+/// Even if the application layer logic already knows it read all the data because it does
+/// its own framing, it must still read from the [`RecvStream`] until `AsyncRead` signals
+/// End Of File (EOF).  Otherwise it risks inadvertently calling [`RecvStream::stop`] if it
+/// drops the stream.  And calling [`RecvStream::stop`] could result in the connected
+/// [`SendStream::finish`] call failing with a [`WriteError::Stopped`] error.
 ///
 /// For example if exactly 10 bytes are to be read, you still need to explicitly read EOF:
 ///
-/// ```ignore
+/// ```no_run
+/// # use quinn::{SendStream, RecvStream};
+/// # async fn func(
+/// #     send_stream: &mut SendStream,
+/// #     recv_stream: &mut RecvStream,
+/// # ) -> anyhow::Result<()>
+/// # {
 /// // In the sending task
 /// send_stream.write(&b"0123456789"[..]).await?;
-/// send_stream.finish()?;
+/// send_stream.finish().await?;
 ///
 /// // In the receiving task
 /// let mut buf = [0u8; 10];
-/// let data = recv_stream.read_exact(&mut buf);
+/// let data = recv_stream.read_exact(&mut buf).await?;
 /// if let Some(chunk) = recv_stream.read_chunk(8, false).await? {
-///     reader.stop(0u8.into()).ok();
+///     recv_stream.stop(0u8.into()).ok();
 /// }
+/// # Ok(())
+/// # }
 /// ```
 ///
 /// Note that in this example the receiver sends an error to the sender if it received some
@@ -55,6 +63,7 @@ use crate::{
 /// [`ReadError`]: crate::ReadError
 /// [`stop()`]: RecvStream::stop
 /// [`SendStream::finish`]: crate::SendStream::finish
+/// [`WriteError::Stopped`]: crate::WriteError::Stopped
 #[derive(Debug)]
 pub struct RecvStream {
     conn: ConnectionRef,