Code review: doc improvements.

Co-Authored-By: Alice Ryhl <alice@ryhl.io>

tokio/src/sync/mutex.rs

@@ -374,10 +374,11 @@ impl<T: ?Sized> Mutex<T> {
     ///
     /// This function panics if called within an asynchronous execution context.
     ///
-    ///   - Consider using [`spawn_blocking()`][crate::runtime::Handle::spawn_blocking]
-    ///     (or [`block_in_place()`][crate::task::block_in_place]) to call, when
-    ///     within an asynchronrous execution context, any function that may
-    ///     call one of these `blocking_` operations.
+    ///   - If you find yourself in an asynchronous execution context and needing
+    ///     to call some (synchronous) function which performs one of these
+    ///     `blocking_` operations, then consider wrapping that call inside
+    ///     [`spawn_blocking()`][crate::runtime::Handle::spawn_blocking]
+    ///     (or [`block_in_place()`][crate::task::block_in_place]).
     ///
     /// # Examples
     ///

tokio/src/sync/rwlock.rs

@@ -470,10 +470,11 @@ impl<T: ?Sized> RwLock<T> {
     ///
     /// This function panics if called within an asynchronous execution context.
     ///
-    ///   - Consider using [`spawn_blocking()`][crate::runtime::Handle::spawn_blocking]
-    ///     (or [`block_in_place()`][crate::task::block_in_place]) to call, when
-    ///     within an asynchronrous execution context, any function that may
-    ///     call one of these `blocking_` operations.
+    ///   - If you find yourself in an asynchronous execution context and needing
+    ///     to call some (synchronous) function which performs one of these
+    ///     `blocking_` operations, then consider wrapping that call inside
+    ///     [`spawn_blocking()`][crate::runtime::Handle::spawn_blocking]
+    ///     (or [`block_in_place()`][crate::task::block_in_place]).
     ///
     /// # Examples
     ///
@@ -498,16 +499,12 @@ impl<T: ?Sized> RwLock<T> {
     ///     *write_lock -= 1;
     ///     drop(write_lock); // release the lock.
     ///
-    ///     // `.read()` and `.blocking_read()` don't block each other.
-    ///     let another_read_lock = rwlock.read().await;
-    ///     assert_eq!(*another_read_lock, 0);
-    ///     drop(another_read_lock);
-    ///
     ///     // Await the completion of the blocking task.
     ///     blocking_task.await.unwrap();
     ///
     ///     // Assert uncontended.
-    ///     assert!(rwlock.try_write().is_ok());
+    ///     let lock = rwlock.try_write().unwrap();
+    ///     assert_eq!(*lock, 0);
     /// }
     /// ```
     #[cfg(feature = "sync")]
@@ -806,10 +803,11 @@ impl<T: ?Sized> RwLock<T> {
     ///
     /// This function panics if called within an asynchronous execution context.
     ///
-    ///   - Consider using [`spawn_blocking()`][crate::runtime::Handle::spawn_blocking]
-    ///     (or [`block_in_place()`][crate::task::block_in_place]) to call, when
-    ///     within an asynchronrous execution context, any function that may
-    ///     call one of these `blocking_` operations.
+    ///   - If you find yourself in an asynchronous execution context and needing
+    ///     to call some (synchronous) function which performs one of these
+    ///     `blocking_` operations, then consider wrapping that call inside
+    ///     [`spawn_blocking()`][crate::runtime::Handle::spawn_blocking]
+    ///     (or [`block_in_place()`][crate::task::block_in_place]).
     ///
     /// # Examples
     ///