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

Code before:
        ///
        /// #[tokio::main]
        /// async fn main() {
        ///     let (first, second) = tokio::join!(
        ///         // do_stuff_async() will always be polled first when woken
        ///         biased;
        ///         do_stuff_async(),
        ///         more_async_work());
        ///
        ///     // do something with the values
        /// }
        /// ```

        #[macro_export]
        #[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
        $join
    };
}

#[cfg(doc)]
doc! {macro_rules! join {
    ($($future:expr),*) => { unimplemented!() }
}}

#[cfg(not(doc))]
doc! {macro_rules! join {
    (@ {
        // Whether to rotate which future is polled first every poll,
        // by incrementing a skip counter
        rotate_poll_order=$rotate_poll_order:literal;

        // One `_` for each branch in the `join!` macro. This is not used once
        // normalization is complete.
        ( $($count:tt)* )

        // The expression `0+1+1+ ... +1` equal to the number of branches.
        ( $($total:tt)* )

        // Normalized join! branches
        $( ( $($skip:tt)* ) $e:expr, )*

    }) => {{
        use $crate::macros::support::{maybe_done, poll_fn, Future, Pin};
        use $crate::macros::support::Poll::{Ready, Pending};

        // Safety: nothing must be moved out of `futures`. This is to satisfy
        // the requirement of `Pin::new_unchecked` called below.
        //
        // We can't use the `pin!` macro for this because `futures` is a tuple
        // and the standard library provides no way to pin-project to the fields
        // of a tuple.

Review comment (suggestion):
We show the syntax of the macro in the docs. The new feature needs to be displayed here. You can modify the invocation marked with `#[cfg(doc)]` to change what is shown here.

![image](https://github.com/user-attachments/assets/a238fa58-8cdd-4ed3-a1a7-f551eed67233)


Code after:
        ///
        /// #[tokio::main]
        /// async fn main() {
        ///     let (first, second) = tokio::join!(
        ///         biased;
        ///         do_stuff_async(),
        ///         more_async_work()
        ///     );
        ///
        ///     // do something with the values
        /// }
        /// ```

        #[macro_export]
        #[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
        $join
    };
}

#[cfg(doc)]
doc! {macro_rules! join {
    ($(biased;)? $($future:expr),*) => { unimplemented!() }
}}

#[cfg(not(doc))]
doc! {macro_rules! join {
    (@ {
        // Type of rotator that controls which inner future to start with
        // when polling our output future.
        rotator=$rotator:ty;

        // One `_` for each branch in the `join!` macro. This is not used once
        // normalization is complete.
        ( $($count:tt)* )

        // The expression `0+1+1+ ... +1` equal to the number of branches.
        ( $($total:tt)* )

        // Normalized join! branches
        $( ( $($skip:tt)* ) $e:expr, )*

    }) => {{
        use $crate::macros::support::{maybe_done, poll_fn, Future, Pin};
        use $crate::macros::support::Poll::{Ready, Pending};

        // Safety: nothing must be moved out of `futures`. This is to satisfy
        // the requirement of `Pin::new_unchecked` called below.
        //
        // We can't use the `pin!` macro for this because `futures` is a tuple
        // and the standard library provides no way to pin-project to the fields
        // of a tuple.