From ef8ab4eefdec56c0a3832f53c30678b2e67eabb5 Mon Sep 17 00:00:00 2001
From: threadexio <pzarganitis@gmail.com>
Date: Sat, 30 Mar 2024 10:08:25 +0200
Subject: [PATCH] docs: add examples for `{send,recv}{_blocking}`

---
 channels/src/error.rs    |  4 ++--
 channels/src/receiver.rs | 36 ++++++++++++++++++++++++++++++----
 channels/src/sender.rs   | 42 ++++++++++++++++++++++++++++++++++++----
 3 files changed, 72 insertions(+), 10 deletions(-)

diff --git a/channels/src/error.rs b/channels/src/error.rs
index 9389fc1..f958707 100644
--- a/channels/src/error.rs
+++ b/channels/src/error.rs
@@ -79,7 +79,7 @@ impl From<HeaderReadError> for VerifyError {
 	}
 }
 
-impl fmt::Display for VerifyError {
+impl Display for VerifyError {
 	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 		match self {
 			Self::VersionMismatch => f.write_str("version mismatch"),
@@ -117,7 +117,7 @@ pub enum ProtocolError {
 	ExceededMaximumSize,
 }
 
-impl fmt::Display for ProtocolError {
+impl Display for ProtocolError {
 	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 		match self {
 			Self::ExceededMaximumSize => {
diff --git a/channels/src/receiver.rs b/channels/src/receiver.rs
index d47168a..897db84 100644
--- a/channels/src/receiver.rs
+++ b/channels/src/receiver.rs
@@ -274,8 +274,20 @@ where
 {
 	/// Attempts to receive a type `T` from the channel.
 	///
-	/// This function will return a future that will complete only when all the
-	/// bytes of `T` have been received.
+	/// # Example
+	///
+	/// ```no_run
+	/// use tokio::net::TcpStream;
+	///
+	/// #[tokio::main]
+	/// async fn main() {
+	///     let stream = TcpStream::connect("127.0.0.1:8080").await.unwrap();
+	///     let mut rx = channels::Receiver::<i32, _, _>::new(stream);
+	///
+	///     let received: i32 = rx.recv().await.unwrap();
+	///     println!("{received}");
+	/// }
+	/// ```
 	pub async fn recv(
 		&mut self,
 	) -> Result<T, RecvError<D::Error, R::Error>> {
@@ -299,8 +311,24 @@ where
 {
 	/// Attempts to receive a type `T` from the channel.
 	///
-	/// This function will block the current thread until every last byte of
-	/// `T` has been received.
+	/// Whether this function blocks execution is dependent on the underlying
+	/// reader.
+	///
+	/// **NOTE:** Non-blocking readers (those who return `WouldBlock`) are _not_
+	/// supported and will _not_ work. If you want non-blocking operation prefer
+	/// the asynchronous version of this function, [`Receiver::recv()`].
+	///
+	/// # Example
+	///
+	/// ```no_run
+	/// use std::net::TcpStream;
+	///
+	/// let stream = TcpStream::connect("127.0.0.1:8080").unwrap();
+	/// let mut rx = channels::Receiver::<i32, _, _>::new(stream);
+	///
+	/// let received: i32 = rx.recv_blocking().unwrap();
+	/// println!("{received}");
+	/// ```
 	pub fn recv_blocking(
 		&mut self,
 	) -> Result<T, RecvError<D::Error, R::Error>> {
diff --git a/channels/src/sender.rs b/channels/src/sender.rs
index a545748..94fa385 100644
--- a/channels/src/sender.rs
+++ b/channels/src/sender.rs
@@ -233,8 +233,23 @@ where
 {
 	/// Attempts to send `data` through the channel.
 	///
-	/// This function will return a future that will complete only when all the
-	/// bytes of `data` have been sent through the channel.
+	/// # Example
+	///
+	/// ```no_run
+	/// use tokio::net::TcpStream;
+	///
+	/// #[tokio::main]
+	/// async fn main() {
+	///     let stream = TcpStream::connect("127.0.0.1:8080").await.unwrap();
+	///     let mut tx = channels::Sender::<i32, _, _>::new(stream);
+	///
+	///     let data = 42;
+	///
+	///     tx.send(&data).await.unwrap();
+	///     // or by taking ownership
+	///     tx.send(data).await.unwrap();
+	/// }
+	/// ```
 	pub async fn send<D>(
 		&mut self,
 		data: D,
@@ -267,8 +282,27 @@ where
 {
 	/// Attempts to send `data` through the channel.
 	///
-	/// This function will block the current thread until every last byte of
-	/// `data` has been sent.
+	/// Whether this function blocks execution is dependent on the underlying
+	/// writer.
+	///
+	/// **NOTE:** Non-blocking writers (those who return `WouldBlock`) are _not_
+	/// supported and will _not_ work. If you want non-blocking operation prefer
+	/// the asynchronous version of this function, [`Sender::send()`].
+	///
+	/// # Example
+	///
+	/// ```no_run
+	/// use std::net::TcpStream;
+	///
+	/// let stream = TcpStream::connect("127.0.0.1:8080").unwrap();
+	/// let mut tx = channels::Sender::<i32, _, _>::new(stream);
+	///
+	/// let data = 42;
+	///
+	/// tx.send_blocking(&data).unwrap();
+	/// // or by taking ownership
+	/// tx.send_blocking(data).unwrap();
+	/// ```
 	pub fn send_blocking<D>(
 		&mut self,
 		data: D,