Code review: doc improvements.

Co-Authored-By: Alice Ryhl <alice@ryhl.io>
tokio-rs · Jan 25, 2022 · 376defc · 376defc
1 parent f5c1f0b
commit 376defc
Show file tree

Hide file tree

Showing 2 changed files with 15 additions and 17 deletions.
diff --git a/tokio/src/sync/mutex.rs b/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
     ///

diff --git a/tokio/src/sync/rwlock.rs b/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,11 +499,6 @@ 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();
     ///
@@ -806,10 +802,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
     ///