From 5e0e00c94d15aa5fb3fc0ebb476c749677a5ad65 Mon Sep 17 00:00:00 2001
From: Jan Tungli <33368331+tungli@users.noreply.github.com>
Date: Sun, 14 Feb 2021 18:45:53 +0100
Subject: [PATCH] small change in `select` example. (#2345)

In the previous example one future always finished first (because of
implementation details), possibly confusing users about what `select`
does.

This commit resolves the issue by being explicit about one future
finishing before the other.

Co-authored-by: tungli <tun@mail.muni.cz>
Co-authored-by: Taiki Endo <te316e89@gmail.com>
---
 futures-util/src/future/select.rs | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/futures-util/src/future/select.rs b/futures-util/src/future/select.rs
index 060bdd14d9..bd44f20f77 100644
--- a/futures-util/src/future/select.rs
+++ b/futures-util/src/future/select.rs
@@ -32,25 +32,33 @@ impl<A: Unpin, B: Unpin> Unpin for Select<A, B> {}
 ///
 /// ```
 /// # futures::executor::block_on(async {
-/// use futures::future::{self, Either};
-/// use futures::pin_mut;
+/// use futures::{
+///     pin_mut,
+///     future::Either,
+///     future::self,
+/// };
 ///
-/// // These two futures have different types even though their outputs have the same type
-/// let future1 = async { 1 };
-/// let future2 = async { 2 };
+/// // These two futures have different types even though their outputs have the same type.
+/// let future1 = async {
+///     future::pending::<()>().await; // will never finish
+///     1
+/// };
+/// let future2 = async {
+///     future::ready(2).await
+/// };
 ///
 /// // 'select' requires Future + Unpin bounds
 /// pin_mut!(future1);
 /// pin_mut!(future2);
 ///
 /// let value = match future::select(future1, future2).await {
-///     Either::Left((value1, _)) => value1, // `value1` is resolved from `future1`
-///                                          // `_` represents `future2`
+///     Either::Left((value1, _)) => value1,  // `value1` is resolved from `future1`
+///                                           // `_` represents `future2`
 ///     Either::Right((value2, _)) => value2, // `value2` is resolved from `future2`
 ///                                           // `_` represents `future1`
 /// };
 ///
-/// assert!(value == 1 || value == 2);
+/// assert!(value == 2);
 /// # });
 /// ```
 ///