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

Code before:
        /// ecosystem utilities such as
        /// [`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-lite::future::or`](https://docs.rs/futures-lite/latest/futures_lite/future/fn.or.html)
        /// - [`futures-lite::future::race`](https://docs.rs/futures-lite/latest/futures_lite/future/fn.race.html)
        /// - [`futures_concurrency::future::Race`](https://docs.rs/futures-concurrency/latest/futures_concurrency/future/trait.Race.html)
        ///
        /// ```ignore
        /// #[tokio::main]
        /// async fn main() {
        ///     let result = futures_lite::future::race(
        ///         async { Ok("ok") }, /* Task A */
        ///         async { Err("error") }, /* Task B */
        ///     )
        ///     .await;
        ///
        ///     match result {
        ///         Ok(output) => println!("First task completed with: {output}"),
        ///         Err(err) => eprintln!("Error occurred: {err}"),
        ///     }
        /// }
        /// ```
        ///
        /// # Examples
        ///
        /// Basic select with two branches.
        ///
        /// ```
        /// async fn do_stuff_async() {
        ///     // async work
        /// }
        ///
        /// async fn more_async_work() {
        ///     // more here
        /// }
        ///
        /// #[tokio::main]
        /// async fn main() {
        ///     tokio::select! {
        ///         _ = do_stuff_async() => {
        ///             println!("do_stuff_async() completed first")
        ///         }
        ///         _ = more_async_work() => {
        ///             println!("more_async_work() completed first")
        ///         }
        ///     };
        /// }
        /// ```
        ///

Review comment (suggestion):
This change should not make the examples harder to find. Either the section needs to be much shorter, or it needs to be below the examples.

Code after:
        /// use tokio::sync::oneshot;
        ///
        /// #[tokio::main]
        /// async fn main() {
        ///     let (tx1, mut rx1) = oneshot::channel();
        ///     let (tx2, mut rx2) = oneshot::channel();
        ///
        ///     tokio::spawn(async move {
        ///         tx1.send("first").unwrap();
        ///     });
        ///
        ///     tokio::spawn(async move {
        ///         tx2.send("second").unwrap();
        ///     });
        ///
        ///     let mut a = None;
        ///     let mut b = None;
        ///
        ///     while a.is_none() || b.is_none() {
        ///         tokio::select! {
        ///             v1 = (&mut rx1), if a.is_none() => a = Some(v1.unwrap()),
        ///             v2 = (&mut rx2), if b.is_none() => b = Some(v2.unwrap()),
        ///         }
        ///     }
        ///
        ///     let res = (a.unwrap(), b.unwrap());
        ///
        ///     assert_eq!(res.0, "first");
        ///     assert_eq!(res.1, "second");
        /// }
        /// ```
        ///
        /// Using the `biased;` mode to control polling order.
        ///
        /// ```
        /// #[tokio::main]
        /// async fn main() {
        ///     let mut count = 0u8;
        ///
        ///     loop {
        ///         tokio::select! {
        ///             // If you run this example without `biased;`, the polling order is
        ///             // pseudo-random, and the assertions on the value of count will
        ///             // (probably) fail.
        ///             biased;
        ///
        ///             _ = async {}, if count < 1 => {
        ///                 count += 1;
        ///                 assert_eq!(count, 1);
        ///             }
        ///             _ = async {}, if count < 2 => {