tweaks to doc comments

Author: jlizen

tokio/src/macros/join.rs

@@ -21,7 +21,7 @@ macro_rules! doc {
         /// The supplied futures are stored inline and do not require allocating a
         /// `Vec`.
         ///
-        /// ### Fairness
+        /// ## Runtime characteristics
         ///
         /// By running all async expressions on the current task, the expressions are
         /// able to run **concurrently** but not in **parallel**. This means all
@@ -32,7 +32,7 @@ macro_rules! doc {
         ///
         /// [`tokio::spawn`]: crate::spawn
         ///
-        /// # Poll Ordering
+        /// ## Fairness
         ///
         /// By default, `join!`'s generated future rotates which contained
         /// future is polled first whenever it is woken.
@@ -74,7 +74,7 @@ macro_rules! doc {
         /// }
         /// ```
         ///
-        ///  Using the `biased;` mode to control polling order.
+        /// Using the `biased;` mode to control polling order.
         ///
         /// ```
         /// async fn do_stuff_async() {
@@ -145,11 +145,9 @@ doc! {macro_rules! join {
 
         const COUNT: u32 = $($total)*;
 
-        // Each time the future created by poll_fn is polled,
-        // if not running in biased mode,
-        // a different future will be polled first
-        // to ensure every future passed to join! gets a chance to make progress even if
-        // one of the futures consumes the whole budget.
+        // Each time the future created by poll_fn is polled, if not using biased mode,
+        // a different future is polled first to ensure every future passed to join!
+        // can make progress even if one of the futures consumes the whole budget.
         let mut rotator = <$rotator>::default();
 
         poll_fn(move |cx| {
@@ -225,14 +223,14 @@ doc! {macro_rules! join {
     () => { async {}.await }
 }}
 
-/// Rotates by one every [`Self::num_skip`] call up to COUNT - 1.
+/// Rotates by one each [`Self::num_skip`] call up to COUNT - 1.
 #[derive(Default, Debug)]
 pub struct Rotator<const COUNT: u32> {
     next: u32,
 }
 
 impl<const COUNT: u32> Rotator<COUNT> {
-    /// Rotates by one every [`Self::num_skip`] call up to COUNT - 1
+    /// Rotates by one each [`Self::num_skip`] call up to COUNT - 1
     #[inline]
     pub fn num_skip(&mut self) -> u32 {
         let num_skip = self.next;
@@ -249,7 +247,7 @@ impl<const COUNT: u32> Rotator<COUNT> {
 pub struct BiasedRotator {}
 
 impl BiasedRotator {
-    /// Always returns 0
+    /// Always returns 0.
     #[inline]
     pub fn num_skip(&mut self) -> u32 {
         0

tokio/src/macros/select.rs

@@ -47,7 +47,7 @@ macro_rules! doc {
         ///    the current call to `select!`. Continue from step 3.
         /// 6. Evaluate the `else` expression. If no else expression is provided, panic.
         ///
-        /// # Runtime characteristics
+        /// ## Runtime characteristics
         ///
         /// By running all async expressions on the current task, the expressions are
         /// able to run **concurrently** but not in **parallel**. This means all
@@ -58,7 +58,7 @@ macro_rules! doc {
         ///
         /// [`tokio::spawn`]: crate::spawn
         ///
-        /// # Fairness
+        /// ## Fairness
         ///
         /// By default, `select!` randomly picks a branch to check first. This provides
         /// some level of fairness when calling `select!` in a loop with branches that
@@ -80,14 +80,14 @@ macro_rules! doc {
         /// always polled, and will not be ignored due to the stream being constantly
         /// ready.
         ///
-        /// # Panics
+        /// ## Panics
         ///
         /// The `select!` macro panics if all branches are disabled **and** there is no
         /// provided `else` branch. A branch is disabled when the provided `if`
         /// precondition returns `false` **or** when the pattern does not match the
         /// result of `<async expression>`.
         ///
-        /// # Cancellation safety
+        /// ## Cancellation safety
         ///
         /// When using `select!` in a loop to receive messages from multiple sources,
         /// you should make sure that the receive call is cancellation safe to avoid

tokio/src/macros/try_join.rs

@@ -19,7 +19,7 @@ macro_rules! doc {
         /// The supplied futures are stored inline and do not require allocating a
         /// `Vec`.
         ///
-        /// ### Runtime characteristics
+        /// ## Runtime characteristics
         ///
         /// By running all async expressions on the current task, the expressions are
         /// able to run **concurrently** but not in **parallel**. This means all
@@ -30,7 +30,7 @@ macro_rules! doc {
         ///
         /// [`tokio::spawn`]: crate::spawn
         ///
-        /// # Fairness
+        /// ## Fairness
         ///
         /// By default, `try_join!`'s generated future rotates which
         /// contained future is polled first whenever it is woken.
@@ -119,7 +119,7 @@ macro_rules! doc {
         ///     }
         /// }
         /// ```
-        ///  Using the `biased;` mode to control polling order.
+        /// Using the `biased;` mode to control polling order.
         ///
         /// ```
         /// async fn do_stuff_async() -> Result<(), &'static str> {
@@ -198,11 +198,9 @@ doc! {macro_rules! try_join {
 
         const COUNT: u32 = $($total)*;
 
-        // Each time the future created by poll_fn is polled,
-        // if not running in biased mode,
-        // a different future will be polled first
-        // to ensure every future passed to join! gets a chance to make progress even if
-        // one of the futures consumes the whole budget.
+        // Each time the future created by poll_fn is polled, if not using biased mode,
+        // a different future is polled first to ensure every future passed to try_join!
+        // can make progress even if one of the futures consumes the whole budget.
         let mut rotator = <$rotator>::default();
 
         poll_fn(move |cx| {