std: update TLS module documentation

3 files changed, 22 insertions, 16 deletions

diff --git a/library/std/src/sys/thread_local/guard/key.rs b/library/std/src/sys/thread_local/guard/key.rs
index e235daf3cc9..ee9d55ddd5e 100644
--- a/library/std/src/sys/thread_local/guard/key.rs
+++ b/library/std/src/sys/thread_local/guard/key.rs
@@ -1,6 +1,6 @@
-//! A lot of UNIX platforms don't have a way to register TLS destructors.
-//! Instead, we use one TLS key to register a callback which will run
-//! iterate through the destructor list.
+//! A lot of UNIX platforms don't have a specialized way to register TLS
+//! destructors for native TLS. Instead, we use one TLS key with a destructor
+//! that will run all native TLS destructors in the destructor list.
 
 use crate::ptr;
 use crate::sys::thread_local::destructors;
diff --git a/library/std/src/sys/thread_local/key/racy.rs b/library/std/src/sys/thread_local/key/racy.rs
index e2eaca197d4..eda8b83bc7f 100644
--- a/library/std/src/sys/thread_local/key/racy.rs
+++ b/library/std/src/sys/thread_local/key/racy.rs
@@ -1,14 +1,10 @@
-//! An implementation of `const`-creatable TLS keys for non-Windows platforms.
+//! A `StaticKey` implementation using racy initialization.
 //!
-//! Most OSs without native TLS will provide a library-based way to create TLS
-//! storage. For each TLS variable, we create a key, which can then be used to
-//! reference an entry in a thread-local table. This then associates each key
-//! with a pointer which we can get and set to store our data.
-//!
-//! Unfortunately, none of these platforms allows creating the key at compile-time,
-//! which means we need a way to lazily create keys (`StaticKey`). Instead of
-//! blocking API like `OnceLock`, we use racy initialization, which should be
-//! more lightweight and avoids circular dependencies with the rest of `std`.
+//! Unfortunately, none of the platforms currently supported by `std` allows
+//! creating TLS keys at compile-time. Thus we need a way to lazily create keys.
+//! Instead of blocking API like `OnceLock`, we use racy initialization, which
+//! should be more lightweight and avoids circular dependencies with the rest of
+//! `std`.
 
 use crate::sync::atomic::{self, AtomicUsize, Ordering};
 
diff --git a/library/std/src/sys/thread_local/mod.rs b/library/std/src/sys/thread_local/mod.rs
index aa2dd48ab49..ef525dd6321 100644
--- a/library/std/src/sys/thread_local/mod.rs
+++ b/library/std/src/sys/thread_local/mod.rs
@@ -40,8 +40,13 @@ cfg_if::cfg_if! {
     }
 }
 
-/// This module maintains a list of TLS destructors for the current thread,
-/// all of which will be run on thread exit.
+/// The native TLS implementation needs a way to register destructors for its data.
+/// This module contains platform-specific implementations of that register.
+///
+/// It turns out however that most platforms don't have a way to register a
+/// destructor for each variable. On these platforms, we keep track of the
+/// destructors ourselves and register (through the [`guard`] module) only a
+/// single callback that runs all of the destructors in the list.
 #[cfg(all(target_thread_local, not(all(target_family = "wasm", not(target_feature = "atomics")))))]
 pub(crate) mod destructors {
     cfg_if::cfg_if! {
@@ -91,7 +96,12 @@ mod guard {
     }
 }
 
-/// This module provides the `StaticKey` abstraction over OS TLS keys.
+/// `const`-creatable TLS keys.
+///
+/// Most OSs without native TLS will provide a library-based way to create TLS
+/// storage. For each TLS variable, we create a key, which can then be used to
+/// reference an entry in a thread-local table. This then associates each key
+/// with a pointer which we can get and set to store our data.
 pub(crate) mod key {
     cfg_if::cfg_if! {
         if #[cfg(any(