util: add examples for FramedRead and FramedWrite (#6310)

tokio-util/src/codec/framed_read.rs

@@ -14,8 +14,12 @@ use std::task::{Context, Poll};
 pin_project! {
     /// A [`Stream`] of messages decoded from an [`AsyncRead`].
     ///
+    /// For examples of how to use `FramedRead` with a codec, see the
+    /// examples on the [`codec`] module.
+    ///
     /// [`Stream`]: futures_core::Stream
     /// [`AsyncRead`]: tokio::io::AsyncRead
+    /// [`codec`]: crate::codec
     pub struct FramedRead<T, D> {
         #[pin]
         inner: FramedImpl<T, D, ReadFrame>,

tokio-util/src/codec/framed_write.rs

@@ -15,7 +15,11 @@ use std::task::{Context, Poll};
 pin_project! {
     /// A [`Sink`] of frames encoded to an `AsyncWrite`.
     ///
+    /// For examples of how to use `FramedWrite` with a codec, see the
+    /// examples on the [`codec`] module.
+    ///
     /// [`Sink`]: futures_sink::Sink
+    /// [`codec`]: crate::codec
     pub struct FramedWrite<T, E> {
         #[pin]
         inner: FramedImpl<T, E, WriteFrame>,

tokio-util/src/codec/mod.rs

@@ -7,6 +7,71 @@
 //! [`AsyncWrite`], to framed streams implementing [`Sink`] and [`Stream`].
 //! Framed streams are also known as transports.
 //!
+//! # Example encoding using `LinesCodec`
+//!
+//! The following example demonstrates how to use a codec such as [`LinesCodec`] to
+//! write framed data. [`FramedWrite`] can be used to achieve this. Data sent to
+//! [`FramedWrite`] are first framed according to a specific codec, and then sent to
+//! an implementor of [`AsyncWrite`].
+//!
+//! ```
+//! use futures::sink::SinkExt;
+//! use tokio_util::codec::LinesCodec;
+//! use tokio_util::codec::FramedWrite;
+//!
+//! #[tokio::main]
+//! async fn main() {
+//!     let buffer = Vec::new();
+//!     let messages = vec!["Hello", "World"];
+//!     let encoder = LinesCodec::new();
+//!
+//!     // FramedWrite is a sink which means you can send values into it
+//!     // asynchronously.
+//!     let mut writer = FramedWrite::new(buffer, encoder);
+//!
+//!     // To be able to send values into a FramedWrite, you need to bring the
+//!     // `SinkExt` trait into scope.
+//!     writer.send(messages[0]).await.unwrap();
+//!     writer.send(messages[1]).await.unwrap();
+//!
+//!     let buffer = writer.get_ref();
+//!
+//!     assert_eq!(buffer.as_slice(), "Hello\nWorld\n".as_bytes());
+//! }
+//!```
+//!
+//! # Example decoding using `LinesCodec`
+//! The following example demonstrates how to use a codec such as [`LinesCodec`] to
+//! read a stream of framed data. [`FramedRead`] can be used to achieve this. [`FramedRead`]
+//! will keep reading from an [`AsyncRead`] implementor until a whole frame, according to a codec,
+//! can be parsed.
+//!
+//!```
+//! use tokio_stream::StreamExt;
+//! use tokio_util::codec::LinesCodec;
+//! use tokio_util::codec::FramedRead;
+//!
+//! #[tokio::main]
+//! async fn main() {
+//!     let message = "Hello\nWorld".as_bytes();
+//!     let decoder = LinesCodec::new();
+//!
+//!     // FramedRead can be used to read a stream of values that are framed according to
+//!     // a codec. FramedRead will read from its input (here `buffer`) until a whole frame
+//!     // can be parsed.
+//!     let mut reader = FramedRead::new(message, decoder);
+//!
+//!     // To read values from a FramedRead, you need to bring the
+//!     // `StreamExt` trait into scope.
+//!     let frame1 = reader.next().await.unwrap().unwrap();
+//!     let frame2 = reader.next().await.unwrap().unwrap();
+//!
+//!     assert!(reader.next().await.is_none());
+//!     assert_eq!(frame1, "Hello");
+//!     assert_eq!(frame2, "World");
+//! }
+//! ```
+//!
 //! # The Decoder trait
 //!
 //! A [`Decoder`] is used together with [`FramedRead`] or [`Framed`] to turn an
@@ -248,6 +313,7 @@
 //! [`AsyncWrite`]: tokio::io::AsyncWrite
 //! [`Stream`]: futures_core::Stream
 //! [`Sink`]: futures_sink::Sink
+//! [`SinkExt`]: futures::sink::SinkExt
 //! [`SinkExt::close`]: https://docs.rs/futures/0.3/futures/sink/trait.SinkExt.html#method.close
 //! [`FramedRead`]: struct@crate::codec::FramedRead
 //! [`FramedWrite`]: struct@crate::codec::FramedWrite