tweak verbiage of try_join/join fairness examples, tweaks to formatting/import organization

Author: jlizen

tokio/src/macros/join.rs

@@ -45,8 +45,8 @@ macro_rules! doc {
         ///
         /// But there is an important caveat to this mode. It becomes your responsibility
         /// to ensure that the polling order of your futures is fair. If for example you
-        /// are joining a stream and a shutdown future, and the stream has a
-        /// huge volume of messages that takes a long time to finish processing per poll, you should
+        /// are joining a long-running server future with a shutdown future, and you want to make
+        /// sure that no new requests are dispatched following a shutdown, you should
         /// place the shutdown future earlier in the `join!` list to ensure that it is
         /// always polled, and will not be delayed due to the stream future taking a long time to return
         /// `Poll::Pending`.
@@ -225,8 +225,8 @@ doc! {macro_rules! join {
     () => { async {}.await }
 }}
 
-#[derive(Default, Debug)]
 /// Rotates by one every [`Self::num_skip`] call up to COUNT - 1.
+#[derive(Default, Debug)]
 pub struct Rotator<const COUNT: u32> {
     next: u32,
 }

tokio/src/macros/support.rs

@@ -3,10 +3,7 @@ cfg_macros! {
 
     pub use std::future::poll_fn;
 
-    // Used with `join!` and `try_join!`
-    pub use crate::macros::join::Rotator;
-    // Used with `join!` and `try_join!`
-    pub use crate::macros::join::BiasedRotator;
+    pub use crate::macros::join::{BiasedRotator, Rotator};
 
     #[doc(hidden)]
     pub fn thread_rng_n(n: u32) -> u32 {
@@ -28,8 +25,6 @@ cfg_macros! {
             Poll::Ready(())
         }
     }
-
-
 }
 
 pub use std::future::{Future, IntoFuture};

tokio/src/macros/try_join.rs

@@ -43,8 +43,8 @@ macro_rules! doc {
         ///
         /// But there is an important caveat to this mode. It becomes your responsibility
         /// to ensure that the polling order of your futures is fair. If for example you
-        /// are joining a stream and a shutdown future, and the stream has a
-        /// huge volume of messages that takes a long time to finish processing per poll, you should
+        /// are try_joining a long-running server future with a shutdown future, and you want to make
+        /// sure that no new requests are dispatched following a shutdown, you should
         /// place the shutdown future earlier in the `try_join!` list to ensure that it is
         /// always polled, and will not be delayed due to the stream future taking a long time to return
         /// `Poll::Pending`.