docs: add examples for {send,recv}{_blocking}

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 => {

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>> {

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,