Rollup merge of rust-lang#85529 - tlyu:trylock-errors, r=JohnTitor

doc: clarify Mutex::try_lock, etc. errors

Clarify error returns from Mutex::try_lock, RwLock::try_read,
RwLock::try_write to make it more obvious that both poisoning
and the lock being already locked are possible errors.

Author: JohnTitor

library/std/src/sync/mutex.rs

@@ -294,8 +294,14 @@ impl<T: ?Sized> Mutex<T> {
     /// # Errors
     ///
     /// If another user of this mutex panicked while holding the mutex, then
-    /// this call will return an error if the mutex would otherwise be
-    /// acquired.
+    /// this call will return the [`Poisoned`] error if the mutex would
+    /// otherwise be acquired.
+    ///
+    /// If the mutex could not be acquired because it is already locked, then
+    /// this call will return the [`WouldBlock`] error.
+    ///
+    /// [`Poisoned`]: TryLockError::Poisoned
+    /// [`WouldBlock`]: TryLockError::WouldBlock
     ///
     /// # Examples
     ///

library/std/src/sync/rwlock.rs

@@ -199,11 +199,17 @@ impl<T: ?Sized> RwLock<T> {
     ///
     /// # Errors
     ///
-    /// This function will return an error if the RwLock is poisoned. An RwLock
-    /// is poisoned whenever a writer panics while holding an exclusive lock. An
-    /// error will only be returned if the lock would have otherwise been
+    /// This function will return the [`Poisoned`] error if the RwLock is poisoned.
+    /// An RwLock is poisoned whenever a writer panics while holding an exclusive
+    /// lock. `Poisoned` will only be returned if the lock would have otherwise been
     /// acquired.
     ///
+    /// This function will return the [`WouldBlock`] error if the RwLock could not
+    /// be acquired because it was already locked exclusively.
+    ///
+    /// [`Poisoned`]: TryLockError::Poisoned
+    /// [`WouldBlock`]: TryLockError::WouldBlock
+    ///
     /// # Examples
     ///
     /// ```
@@ -281,10 +287,17 @@ impl<T: ?Sized> RwLock<T> {
     ///
     /// # Errors
     ///
-    /// This function will return an error if the RwLock is poisoned. An RwLock
-    /// is poisoned whenever a writer panics while holding an exclusive lock. An
-    /// error will only be returned if the lock would have otherwise been
-    /// acquired.
+    /// This function will return the [`Poisoned`] error if the RwLock is
+    /// poisoned. An RwLock is poisoned whenever a writer panics while holding
+    /// an exclusive lock. `Poisoned` will only be returned if the lock would have
+    /// otherwise been acquired.
+    ///
+    /// This function will return the [`WouldBlock`] error if the RwLock could not
+    /// be acquired because it was already locked exclusively.
+    ///
+    /// [`Poisoned`]: TryLockError::Poisoned
+    /// [`WouldBlock`]: TryLockError::WouldBlock
+    ///
     ///
     /// # Examples
     ///