clean up some documentation

Signed-off-by: Connor Tsui <[email protected]>

Author: connortsui20

library/std/src/sync/mod.rs

@@ -142,7 +142,7 @@
 //!   most one thread at a time is able to access some data.
 //!
 //! - [`Once`]: Used for a thread-safe, one-time global initialization routine.
-//!   Mostly useful for implementing other types like `OnceLock`.
+//!   Mostly useful for implementing other types like [`OnceLock`].
 //!
 //! - [`OnceLock`]: Used for thread-safe, one-time initialization of a
 //!   variable, with potentially different initializers based on the caller.

library/std/src/sync/poison.rs

@@ -13,8 +13,8 @@
 //! the panics are recognized reliably or on a best-effort basis depend on the
 //! primitive. See [Overview](#overview) below.
 //!
-//! For the alternative implementations that do not employ poisoning,
-//! see [`std::sync::nonpoison`].
+//! The synchronization objects in this module have alternative implementations that do not employ
+//! poisoning in the [`std::sync::nonpoison`] module.
 //!
 //! [`std::sync::nonpoison`]: crate::sync::nonpoison
 //!
@@ -42,14 +42,6 @@
 //!   [`Mutex::lock()`] returns a [`LockResult`], providing a way to deal with
 //!   the poisoned state. See [`Mutex`'s documentation](Mutex#poisoning) for more.
 //!
-//! - [`Once`]: A thread-safe way to run a piece of code only once.
-//!   Mostly useful for implementing one-time global initialization.
-//!
-//!   [`Once`] is reliably poisoned if the piece of code passed to
-//!   [`Once::call_once()`] or [`Once::call_once_force()`] panics.
-//!   When in poisoned state, subsequent calls to [`Once::call_once()`] will panic too.
-//!   [`Once::call_once_force()`] can be used to clear the poisoned state.
-//!
 //! - [`RwLock`]: Provides a mutual exclusion mechanism which allows
 //!   multiple readers at the same time, while allowing only one
 //!   writer at a time. In some cases, this can be more efficient than
@@ -59,6 +51,11 @@
 //!   Note, however, that an `RwLock` may only be poisoned if a panic occurs
 //!   while it is locked exclusively (write mode). If a panic occurs in any reader,
 //!   then the lock will not be poisoned.
+//!
+//! Note that the [`Once`] type also employs poisoning, but since it has non-poisoning `force`
+//! methods available on it, there is no separate `nonpoison` and `poison` version.
+//!
+//! [`Once`]: crate::sync::Once
 
 // If we are not unwinding, `PoisonError` is uninhabited.
 #![cfg_attr(not(panic = "unwind"), expect(unreachable_code))]