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

Code before:
        /// async fn some_async_work() {
        /// # time::sleep(Duration::from_millis(10)).await;
        ///     // do work
        /// }
        ///
        /// #[tokio::main]
        /// async fn main() {
        ///     let sleep = time::sleep(Duration::from_millis(50));
        ///     tokio::pin!(sleep);
        ///
        ///     loop {
        ///         tokio::select! {
        ///             _ = &mut sleep => {
        ///                 println!("operation timed out");
        ///                 break;
        ///             }
        ///             _ = some_async_work() => {
        ///                 println!("operation completed");
        ///             }
        ///         }
        ///     }
        /// }
        /// ```
        /// # Alternatives from the Ecosystem
        ///
        /// The select! macro is a powerful tool for managing multiple asynchronous
        /// branches, enabling tasks to run concurrently within the same thread. However,
        /// its use can introduce challenges, particularly around cancellation safety, which
        /// can lead to subtle and hard-to-debug errors. For many use cases, ecosystem
        /// alternatives may be preferable as they mitigate these concerns by offering
        /// clearer syntax, more predictable control flow, and reducing the need to manually
        /// handle issues like fuse semantics or cancellation safety.
        ///
        /// ## Merging Streams
        ///
        /// For cases where `loop { select! { ... } }` is used to poll multiple tasks,
        /// stream merging offers a concise alternative, inherently handle cancellation-safe
        /// processing, removing the risk of data loss. Libraries like
        /// [`tokio_stream`](https://docs.rs/tokio-stream/latest/tokio_stream/),
        /// [`futures::stream`](https://docs.rs/futures/latest/futures/stream/) and
        /// [`futures_concurrency`](https://docs.rs/futures-concurrency/latest/futures_concurrency/)
        /// provide tools for merging streams and handling their outputs sequentially.
        ///
        /// ### Example with `select!`
        ///
        /// ```
        /// struct File;
        /// struct Channel;
        /// struct Socket;
        ///
        /// impl Socket {

Review comment (suggestion):
```suggestion
        /// The `select!` macro is a powerful tool for managing multiple asynchronous
```

Code after:
        /// async fn some_async_work() {
        /// # time::sleep(Duration::from_millis(10)).await;
        ///     // do work
        /// }
        ///
        /// #[tokio::main]
        /// async fn main() {
        ///     let sleep = time::sleep(Duration::from_millis(50));
        ///     tokio::pin!(sleep);
        ///
        ///     loop {
        ///         tokio::select! {
        ///             _ = &mut sleep => {
        ///                 println!("operation timed out");
        ///                 break;
        ///             }
        ///             _ = some_async_work() => {
        ///                 println!("operation completed");
        ///             }
        ///         }
        ///     }
        /// }
        /// ```
        /// # Alternatives from the Ecosystem
        ///
        /// The `select!` macro is a powerful tool for managing multiple asynchronous
        /// branches, enabling tasks to run concurrently within the same thread. However,
        /// its use can introduce challenges, particularly around cancellation safety, which
        /// can lead to subtle and hard-to-debug errors. For many use cases, ecosystem
        /// alternatives may be preferable as they mitigate these concerns by offering
        /// clearer syntax, more predictable control flow, and reducing the need to manually
        /// handle issues like fuse semantics or cancellation safety.
        ///
        /// ## Merging Streams
        ///
        /// For cases where `loop { select! { ... } }` is used to poll multiple tasks,
        /// stream merging offers a concise alternative, inherently handle cancellation-safe
        /// processing, removing the risk of data loss. Libraries such as [`tokio_stream`],
        /// [`futures::stream`] and [`futures_concurrency`] provide tools for merging
        /// streams and handling their outputs sequentially.
        ///
        /// [`tokio_stream`]: https://docs.rs/tokio-stream/latest/tokio_stream/
        /// [`futures::stream`]: https://docs.rs/futures/latest/futures/stream/
        /// [`futures_concurrency`]: https://docs.rs/futures-concurrency/latest/futures_concurrency/
        ///
        /// ### Example with `select!`
        ///
        /// ```
        /// struct File;
        /// struct Channel;
        /// struct Socket;