Repository: tokio-rs/tokio
File: tokio/src/macros/select.rs (Rust)

Code before:
        /// async fn read_send(_file: &mut File, _channel: &mut Channel) {
        ///     // do work that is not cancel safe
        /// }
        ///
        /// enum Message {
        ///     Stop,
        ///     Sent,
        ///     Data(Vec<u8>),
        /// }
        ///
        /// #[tokio::main]
        /// async fn main() {
        ///     // open our IO types
        ///     let file = File;
        ///     let channel = Channel;
        ///     let socket = Socket;
        ///
        ///     let a = unfold((file, channel), |(mut file, mut channel)| async {
        ///         read_send(&mut file, &mut channel).await;
        ///         Some((Message::Sent, (file, channel)))
        ///     });
        ///     let b = unfold(socket, |mut socket| async {
        ///         let data = socket.read_packet().await;
        ///         Some((Message::Data(data), socket))
        ///     });
        ///     let c = iter([Message::Stop]);
        ///
        ///     let mut s = pin!(a.merge(b).merge(c));
        ///     while let Some(msg) = s.next().await {
        ///         match msg {
        ///             Message::Data(_data) => { /* ... */ }
        ///             Message::Sent => continue,
        ///             Message::Stop => break,
        ///         }
        ///     }
        /// }
        /// ```
        ///
        /// ## Racing Futures
        ///
        /// If you need to wait for the first completion among several asynchronous tasks,
        /// ecosystem utilities such as
        /// [`futures`](https://docs.rs/futures/latest/futures/),
        /// [`futures-lite`](https://docs.rs/futures-lite/latest/futures_lite/) or
        /// [`futures-concurrency`](https://docs.rs/futures-concurrency/latest/futures_concurrency/)
        /// provide streamlined syntax for racing futures:
        ///
        /// - [`futures_concurrency::future::Race`](https://docs.rs/futures-concurrency/latest/futures_concurrency/future/trait.Race.html)
        /// - [`futures::select!`](https://docs.rs/futures/latest/futures/macro.select.html)
        /// - [`futures::stream::select_all`](https://docs.rs/futures/latest/futures/stream/select_all/index.html) (for streams)
        /// - [`futures_lite::future::or`](https://docs.rs/futures-lite/latest/futures_lite/future/fn.or.html)

Review comment (suggestion):
I think this would be easier to read if it looks like this:
```suggestion
        ///     let c = stream::iter([Message::Stop]);
```

Code after:
        /// }
        ///
        /// async fn read_send(_file: &mut File, _channel: &mut Channel) {
        ///     // do work that is not cancel safe
        /// }
        ///
        /// enum Message {
        ///     Stop,
        ///     Sent,
        ///     Data(Vec<u8>),
        /// }
        ///
        /// #[tokio::main]
        /// async fn main() {
        ///     // open our IO types
        ///     let file = File;
        ///     let channel = Channel;
        ///     let socket = Socket;
        ///
        ///     let a = unfold((file, channel), |(mut file, mut channel)| async {
        ///         read_send(&mut file, &mut channel).await;
        ///         Some((Message::Sent, (file, channel)))
        ///     });
        ///     let b = unfold(socket, |mut socket| async {
        ///         let data = socket.read_packet().await;
        ///         Some((Message::Data(data), socket))
        ///     });
        ///     let c = tokio_stream::iter([Message::Stop]);
        ///
        ///     let mut s = pin!(a.merge(b).merge(c));
        ///     while let Some(msg) = s.next().await {
        ///         match msg {
        ///             Message::Data(_data) => { /* ... */ }
        ///             Message::Sent => continue,
        ///             Message::Stop => break,
        ///         }
        ///     }
        /// }
        /// ```
        ///
        /// ## Racing Futures
        ///
        /// If you need to wait for the first completion among several asynchronous tasks,
        /// ecosystem utilities such as
        /// [`futures`](https://docs.rs/futures/latest/futures/),
        /// [`futures-lite`](https://docs.rs/futures-lite/latest/futures_lite/) or
        /// [`futures-concurrency`](https://docs.rs/futures-concurrency/latest/futures_concurrency/)
        /// provide streamlined syntax for racing futures:
        ///
        /// - [`futures_concurrency::future::Race`](https://docs.rs/futures-concurrency/latest/futures_concurrency/future/trait.Race.html)
        /// - [`futures::select`](https://docs.rs/futures/latest/futures/macro.select.html)