Rollup merge of #31345 - kamalmarhubi:book-docs-special-section-errors, r=steveklabnik

This matches the usage in the standard library's documentation.

src/libstd/fs.rs

@@ -70,7 +70,7 @@ pub struct Metadata(fs_imp::FileAttr);
 /// information like the entry's path and possibly other metadata can be
 /// learned.
 ///
-/// # Failure
+/// # Errors
 ///
 /// This `io::Result` will be an `Err` if there's some sort of intermittent
 /// IO error during iteration.

src/libstd/sync/condvar.rs

@@ -129,7 +129,7 @@ impl Condvar {
     /// the predicate must always be checked each time this function returns to
     /// protect against spurious wakeups.
     ///
-    /// # Failure
+    /// # Errors
     ///
     /// This function will return an error if the mutex being waited on is
     /// poisoned when this thread re-acquires the lock. For more information,

src/libstd/sync/mutex.rs

@@ -205,7 +205,7 @@ impl<T: ?Sized> Mutex<T> {
     /// held. An RAII guard is returned to allow scoped unlock of the lock. When
     /// the guard goes out of scope, the mutex will be unlocked.
     ///
-    /// # Failure
+    /// # Errors
     ///
     /// If another user of this mutex panicked while holding the mutex, then
     /// this call will return an error once the mutex is acquired.
@@ -223,7 +223,7 @@ impl<T: ?Sized> Mutex<T> {
     ///
     /// This function does not block.
     ///
-    /// # Failure
+    /// # Errors
     ///
     /// If another user of this mutex panicked while holding the mutex, then
     /// this call will return failure if the mutex would otherwise be
@@ -250,7 +250,7 @@ impl<T: ?Sized> Mutex<T> {
 
     /// Consumes this mutex, returning the underlying data.
     ///
-    /// # Failure
+    /// # Errors
     ///
     /// If another user of this mutex panicked while holding the mutex, then
     /// this call will return an error instead.
@@ -280,7 +280,7 @@ impl<T: ?Sized> Mutex<T> {
     /// Since this call borrows the `Mutex` mutably, no actual locking needs to
     /// take place---the mutable borrow statically guarantees no locks exist.
     ///
-    /// # Failure
+    /// # Errors
     ///
     /// If another user of this mutex panicked while holding the mutex, then
     /// this call will return an error instead.

src/libstd/sync/rwlock.rs

@@ -169,7 +169,7 @@ impl<T: ?Sized> RwLock<T> {
     /// Returns an RAII guard which will release this thread's shared access
     /// once it is dropped.
     ///
-    /// # Failure
+    /// # 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.
@@ -192,7 +192,7 @@ impl<T: ?Sized> RwLock<T> {
     /// This function does not provide any guarantees with respect to the ordering
     /// of whether contentious readers or writers will acquire the lock first.
     ///
-    /// # Failure
+    /// # 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
@@ -217,7 +217,7 @@ impl<T: ?Sized> RwLock<T> {
     /// Returns an RAII guard which will drop the write access of this rwlock
     /// when dropped.
     ///
-    /// # Failure
+    /// # 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.
@@ -240,7 +240,7 @@ impl<T: ?Sized> RwLock<T> {
     /// This function does not provide any guarantees with respect to the ordering
     /// of whether contentious readers or writers will acquire the lock first.
     ///
-    /// # Failure
+    /// # 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
@@ -269,7 +269,7 @@ impl<T: ?Sized> RwLock<T> {
 
     /// Consumes this `RwLock`, returning the underlying data.
     ///
-    /// # Failure
+    /// # 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
@@ -301,7 +301,7 @@ impl<T: ?Sized> RwLock<T> {
     /// Since this call borrows the `RwLock` mutably, no actual locking needs to
     /// take place---the mutable borrow statically guarantees no locks exist.
     ///
-    /// # Failure
+    /// # 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

src/libstd/sys/common/remutex.rs

@@ -78,7 +78,7 @@ impl<T> ReentrantMutex<T> {
     /// calling this method already holds the lock, the call shall succeed without
     /// blocking.
     ///
-    /// # Failure
+    /// # Errors
     ///
     /// If another user of this mutex panicked while holding the mutex, then
     /// this call will return failure if the mutex would otherwise be
@@ -95,7 +95,7 @@ impl<T> ReentrantMutex<T> {
     ///
     /// This function does not block.
     ///
-    /// # Failure
+    /// # Errors
     ///
     /// If another user of this mutex panicked while holding the mutex, then
     /// this call will return failure if the mutex would otherwise be